"Fossies" - the Fresh Open Source Software Archive  

Source code changes of the file "libs/maildir/maildirmake.1.in" between
sqwebmail-5.9.3.tar.bz2 and sqwebmail-6.0.0.tar.bz2

About: SqWebMail is a CGI Webmail client for Maildir mailboxes (module of the Courier mail server).

maildirmake.1.in  (sqwebmail-5.9.3.tar.bz2):maildirmake.1.in  (sqwebmail-6.0.0.tar.bz2)
'\" t '\" t
.\"<!-- Copyright 1998 - 2009 Double Precision, Inc. See COPYING for --> .\"<!-- Copyright 1998 - 2018 Double Precision, Inc. See COPYING for -->
.\"<!-- distribution information. --> .\"<!-- distribution information. -->
.\" Title: maildirmake .\" Title: maildirmake
.\" Author: Sam Varshavchik .\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 07/28/2018 .\" Date: 07/29/2018
.\" Manual: Double Precision, Inc. .\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server .\" Source: Courier Mail Server
.\" Language: English .\" Language: English
.\" .\"
.TH "MAILDIRMAKE" "1" "07/28/2018" "Courier Mail Server" "Double Precision, Inc\ &." .TH "MAILDIRMAKE" "1" "07/29/2018" "Courier Mail Server" "Double Precision, Inc\ &."
.\" ----------------------------------------------------------------- .\" -----------------------------------------------------------------
.\" * Define some portability stuff .\" * Define some portability stuff
.\" ----------------------------------------------------------------- .\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673 .\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq .ie \n(.g .ds Aq \(aq
.el .ds Aq ' .el .ds Aq '
.\" ----------------------------------------------------------------- .\" -----------------------------------------------------------------
skipping to change at line 41 skipping to change at line 41
.\" ----------------------------------------------------------------- .\" -----------------------------------------------------------------
.SH "NAME" .SH "NAME"
maildirmake \- create maildirs and maildir folders maildirmake \- create maildirs and maildir folders
.SH "SYNOPSIS" .SH "SYNOPSIS"
.HP \w'\fBmaildirmake\fR\ 'u .HP \w'\fBmaildirmake\fR\ 'u
\fBmaildirmake\fR [options...] {\fImaildir\fR} \fBmaildirmake\fR [options...] {\fImaildir\fR}
.SH "DESCRIPTION" .SH "DESCRIPTION"
.PP .PP
The The
\fBmaildirmake\fR \fBmaildirmake\fR
command creates maildirs, and maildir folders\&. This documentation describes th e command creates maildirs, and maildir folders and performs some routine maintena nce on them\&. This documentation describes the
\fBmaildirmake\fR \fBmaildirmake\fR
command from the command from the
Courier Courier
mail server, which creates an extended form of maildirs that implements addition al extensions beyond the basic maildir properties that were first implemented in the Qmail mail server\&. mail server, which creates an extended form of maildirs that implements addition al extensions beyond the basic maildir properties that were first implemented in the Qmail mail server\&.
.SH "OPTIONS" .SH "OPTIONS"
.PP .PP
\-S \-S
.RS 4 .RS 4
create a "sharable" maildir\&. A sharable maildir has slightly different permiss ions which allows creation of publicly\-shared folders\&. create a "sharable" maildir\&. A sharable maildir has slightly different permiss ions which allows creation of publicly\-shared folders\&.
.RE .RE
.PP .PP
\-q \fIquota\fR \-q \fIquota\fR
.RS 4 .RS 4
install a quota on the maildir\&. See install a quota on the maildir\&. See
\m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2, below\&. \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2
for more information\&. The specified maildir gets automatically created if it d
oes not exist; otherwise the existing maildir\*(Aqs quota gets updated\&.
.RE .RE
.PP .PP
\-f \fIfolder\fR \-f \fIfolder\fR
.RS 4 .RS 4
do not create a maildir, but create a folder in an existing maildir\&. do not create a maildir, but create a folder in an existing maildir\&.
.RE .RE
.PP .PP
\-F \fIfolder\fR \-F \fIfolder\fR
.RS 4 .RS 4
Like the Like the
\-f \-f
option, except that the folder\*(Aqs name is given using the system locale\*(Aqs character set\&. Non\-Latin characters in the folder\*(Aqs name must be given t o the option, except that the folder\*(Aqs name is given using the system locale\*(Aqs character set\&. Non\-Latin characters in the folder\*(Aqs name must be given t o the
\-f \-f
option using IMAP\*(Aqs modified\-UTF7 encoding\&. The option using IMAP\*(Aqs UTF8 encoding\&. The
\-F \-F
option takes the folder name specified using the console\*(Aqs character set\&.\ &. option takes the folder name specified using the console\*(Aqs character set\&.
.RE .RE
.PP .PP
\-s \fImode\fR \-s \fImode\fR
.RS 4 .RS 4
create a publicly accessible folder in an existing sharable maildir\&. First, us e the create a publicly accessible folder in an existing sharable maildir\&. First, us e the
\fB\-S\fR \fB\-S\fR
option to create a sharable maildir\&. Then, run option to create a sharable maildir\&. Then, run
\fBmaildirmake\fR \fBmaildirmake\fR
again with the again with the
\fB\-s\fR \fB\-s\fR
skipping to change at line 98 skipping to change at line 99
write write
\- anyone can read and write messages to this folder; \- anyone can read and write messages to this folder;
group group
\- only allow members of your own system group to access messages in this folder (instead of everyone)\&. \- only allow members of your own system group to access messages in this folder (instead of everyone)\&.
.RE .RE
.PP .PP
\-\-add \fIname\fR=\fIpathname\fR, \-\-del \fIname\fR \-\-add \fIname\fR=\fIpathname\fR, \-\-del \fIname\fR
.RS 4 .RS 4
create or delete the directories and links needed to access shared folders\&. Se e below for more information\&. create or delete the directories and links needed to access shared folders\&. Se e below for more information\&.
.RE .RE
.PP
\-\-checkutf8 \fImaildir\fR \fImaildirfilter\fR
.RS 4
Perform a sanity check to verify that a pre\-unicode format maildir can be conve
rted to a unicode\-format maildir\&. See
\(lqConverting pre\-unicode format maildirs\(rq, below, for more information\&.
.RE
.PP
\-\-convutf8 \fImaildir\fR \fImaildirfilter\fR
.RS 4
Convert a pre\-unicode format maildir can be converted to a unicode\-format mail
dir\&. See
\(lqConverting pre\-unicode format maildirs\(rq, below, for more information\&.
.RE
.SS "FOLDERS" .SS "FOLDERS"
.PP .PP
This This
\fBmaildirmake\fR \fBmaildirmake\fR
command supports enhanced maildirs that contain folders\&. command supports enhanced maildirs that contain folders\&.
.PP .PP
By itself, By itself,
\fBmaildirmake\fR \fBmaildirmake\fR
makes a new subdirectory makes a new subdirectory
\fImaildir\fR, and creates all the necessary structures\&. The \fImaildir\fR, and creates all the necessary structures\&. The
skipping to change at line 250 skipping to change at line 263
is a short nickname for the sharable maildir, is a short nickname for the sharable maildir,
<tab> <tab>
is a single tab character, is a single tab character,
\fIpath\fR \fIpath\fR
is the pathname to the sharable maildir\&. is the pathname to the sharable maildir\&.
.SS "ACCESSING SHARED FOLDERS" .SS "ACCESSING SHARED FOLDERS"
.PP .PP
You may have read or write access to a shared folder\&. If you have write access , you can add messages to the shared folder\&. You can also delete messages that you\*(Aqve added\&. You may have read or write access to a shared folder\&. If you have write access , you can add messages to the shared folder\&. You can also delete messages that you\*(Aqve added\&.
.PP .PP
Anyone can create a sharable maildir, so if the sharable maildir is actually cre ated by you, can can delete any message, not just your own\&. Anyone can create a sharable maildir, so if the sharable maildir is actually cre ated by you, can can delete any message, not just your own\&.
.SH "CONVERTING PRE\-UNICODE FORMAT MAILDIRS"
.PP
This section is relevant to:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Updating
Courier\-IMAP
to version 5\&.0, and later, from prior versions of
Courier\-IMAP, or:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Updating
SqWebmail
to version 6\&.0, and later, from prior versions of
SqWebmail, or:
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Updating Courier to version 1\&.0, and later, from prior versions of Courier\&.
.RE
.PP
These versions have been updated to implement native Unicode support in several
E\-mail\-related protocols\&. It is already expected that updating Internet stan
dards to use native Unicode\-formatted E\-mail messages will not be 100% backwar
ds\-compatible, in terms of E\-mail client support\&. Given that, this major upd
ate to Unicode will also introduce some backwards\-incompatible changes to the i
nternal structure of maildirs, as a long term major to simplify Unicode support
going forward\&. Might as well go through the pain of a major upgrade once\&.
.PP
\fBmaildirmake\fR\*(Aqs
\fB\-\-checkutf8\fR
and
\fB\-\-convutf8\fR
options are tools to aid in conversion of existing mailbox to the new Unicode\-b
ased naming standard\&.
.SS "Background"
.PP
Mail folders in a maildir are hidden subdirectories\&. For example: a folder nam
e
\(lqMailing list\(rq
is a maildir subdirectory named
$HOME/Maildir/\&.Mailing list
(with
$HOME/Maildir
being the main mailbox)\&.
.PP
Prior to the unicode update, non\-English characters in folder names were implem
ented using a convention that was derived from the non\-standard
\(lqmodified\-UTF7\(rq
encoding used by IMAP\&. A folder named
\(lqRésumé\(rq
was in a maildir subdirectory named
$HOME/Maildir/\&.R&AOk\-sum&AOk\-\&. The current versions of Courier,
Courier\-IMAP, and SqWebmail, will simply create
$HOME/Maildir/\&.Résumé
using the
UTF8
encoding, which will appear simply as a
\(lq\&.Résumé\(rq
(hidden) subdirectory on modern UTF8\-based systems\&.
.PP
Consequently, any existing maildirs that have non\-English folders must be conve
rted as part of updating to the current version of Courier,
Courier\-IMAP, and SqWebmail from pre\-unicode versions\&. At this time this doe
s not occur as part of automatically updating to the current version, and must b
e done manually given the wide variety of individual mail server configurations
that are possible\&.
.SS "Unicode conversion overview"
.PP
Updating from pre\-unicode versions involves:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Renaming the actual maildir folders,
$HOME/Maildir/\&.\fInames\fR
into unicode names (using
UTF8)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Updating the
$HOME/Maildir/courierimapsubscribed, which is a list of subscribed IMAP folders,
if it exists\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Updating any
maildrop
mail filtering recipe,
$HOME/\&.mailfilter, if it exists, to reference the unicode maildir folders; or
updating any custom site mail filtering engine that delivers to maildir folders,
to reference the correct subdirectory names\&.
.RE
.SS "Unicode conversion steps"
.PP
The
\fB\-\-checkutf8\fR
and
\fB\-\-convutf8\fR
options to
\fBmaildirmake\fR
convert a single maildir to the new unicode format:
.sp
.if n \{\
.RS 4
.\}
.nf
$ \&./maildirmake \-\-checkutf8 ~/Maildir ~/\&.mailfilter
Checking /home/mrsam/Maildir:
Mail filter to INBOX\&.R&AOk\-sum&AOk\- updated to INBOX\&.Résumé
Subscription to INBOX\&.R&AOk\-sum&AOk\- changed to INBOX\&.Résumé
Rename INBOX\&.R&AOk\-sum&AOk\- to INBOX\&.Résumé
Verified /home/mrsam/Maildir/courierimapsubscribed
Verified /home/mrsam/\&.mailfilter
$ \&./maildirmake \-\-convutf8 ~/Maildir ~/\&.mailfilter
Checking /home/mrsam/Maildir:
Mail filter to INBOX\&.R&AOk\-sum&AOk\- updated to INBOX\&.Résumé
Subscription to INBOX\&.R&AOk\-sum&AOk\- changed to INBOX\&.Résumé
Rename INBOX\&.R&AOk\-sum&AOk\- to INBOX\&.Résumé
Updating /home/mrsam/Maildir/courierimapsubscribed
Updating /home/mrsam/\&.mailfilter
.fi
.if n \{\
.RE
.\}
.PP
\fB\-\-checkutf8\fR
goes through the motions of converting a single maildir to Unicode, but without
making any actual changes\&.
\fB\-\-convutf8\fR
does the conversion for real\&. The first required parameter is the maildir to c
onvert\&. The second parameter is optional, and specifies the corresponding
\fBmaildrop\fR
filtering recipe,
\fIbut only if \fR\fISqWebMail\fR
generates the mail filtering recipes\&.
SqWebMail\*(Aqs mail filtering recipes are parsable, and can be automatically\-c
onverted\&. Non\-SqWebMail\-generated
\&.mailfilters cannot be converted automatically\&. The second parameter must be
omitted, and the mail filtering recipe must be converted by hand\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
All this work is only needed if maildirs have folders with non\-English names\&.
Ignore everything you\*(Aqve just read if all folder names are English\-only\&.
\fB\-\-checkutf8\fR
and
\fB\-\-convutf8\fR
will not do anything, and nothing needs to be done\&.
.sp .5v
.RE
.PP
To convert all mailboxes to Unicode all at once:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A shell script needs to run the
\fB\-\-checkutf8\fR
option for every mailbox\&. A list of each account\*(Aqs maildir needs to be pre
pared in advance, together with the corresponding
\&.mailfilter
(where appropriate)\&. courier\-authlib\*(Aqs
\fBauthenumerate\fR
command is usually a good starting point\&. It\*(Aqs ok to explicitly specify ea
ch mailbox\*(Aqs
\&.mailfilter, when using
SqWebMail
even if a particular mailbox does not use it\&. It will be ignored\&. The list o
f all accounts\*(Aq maildirs gets converted to a shell script that runs
\fBmaildirmake\fR
with the
\fB\-\-checkutf8\fR
option\&. The script should report any maildir whose
\fB\-\-checkutf8\fR
option reports an error, and
\fBmaildirmake\fR
exits with a non\-zero status\&.
.sp
It is safe to run
\fB\-\-checkutf8\fR
without shutting down your mail server\&. A non\-zero exit from
\fB\-\-checkutf8\fR
indicates a problem (see below) for a particular maildir\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Once
\fB\-\-checkutf8\fR
does not find any problems with any mailbox, shut down the mail server, run
\fB\-\-checkutf8\fR
one more time for all mailboxes, then if everything goes well, upgrade
Courier,
Courier\-IMAP, or
SqWebMail
and run
\fB\-\-convutf8\fR
on every mailbox before restarting the server\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
\fB\-\-convutf8\fR
is a one\-shot deal\&. Do not run
\fB\-\-convutf8\fR
a second time after it successfully converted a maildir\&. In nearly all cases n
othing will happen, but there are rare edge cases where some folder names may ge
t garbled, or it fails completely\&.
.sp .5v
.RE
.SS "Resolving unicode conversion problems"
.PP
The only likely problems that might be encountered is the fall\-out from buggy I
MAP clients that did not follow the pre\-Unicode naming convention for non\-Lati
n folder names\&. The customized IMAP
\(lqmodified\-UTF7\(rq
encoding convention for non\-Latin folder names is mostly an IMAP client convent
ion, and the pre\-Unicode version of
Courier\-IMAP
did not enforce it\&. The server just uses the name from the IMAP client, as is\
&.
.PP
Unicode conversion (\fB\-\-checkutf8\fR
or
\fB\-\-convutf8\fR) fails if it finds a folder name that does not correctly use
IMAP\*(Aqs
\(lqmodified\-UTF7\(rq
encoding\&. This can only be resolved manually, by renaming the folder\&. This m
ay also involve manually editing
courierimapsubscribed
and
\&.mailfilter
if they exist\&. The bad folder name should be removed from
courierimapsubscribed\&. For
\&.mailfilter
it is sufficient to remove only the comments that precede the actual
\fBmaildrop\fR
rule, and
\fB\-\-convutf8\fR
will remove the entire rule, by itself\&.
\fB\-\-convutf8\fR
actually reads only the machine\-parsable comments in
\fBSqWebMail\fR\-generated
\&.mailfilter
(plus a few other things in the file), and replaces the
\&.mailfilter
with the Unicode version based solely on the parsed data\&.
.SS "After the Unicode conversion"
.PP
The current, Unicode version of
Courier\-IMAP
supports both Unicode and non\-Unicode IMAP clients; however unlike the pre\-Uni
code version,
Courier\-IMAP
rejects requests from non\-Unicode IMAP clients to use or create folders that ar
e not properly encoded\&.
.PP
Encountering a bad folder during conversion strongly suggests the presence of an
IMAP client that does not correctly encode non\-English folder names\&. Such an
IMAP client will likely have problems after the conversion\&.
.SH "SEE ALSO" .SH "SEE ALSO"
.PP .PP
\m[blue]\fB\fBmaildir\fR(5)\fR\m[]\&\s-2\u[3]\d\s+2, \m[blue]\fB\fBmaildir\fR(5)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fB\fBmaildiracl\fR(1)\fR\m[]\&\s-2\u[2]\d\s+2, \m[blue]\fB\fBmaildiracl\fR(1)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fB\fBmaildirkw\fR(1)\fR\m[]\&\s-2\u[4]\d\s+2, \m[blue]\fB\fBmaildirkw\fR(1)\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[5]\d\s+2, \m[blue]\fB\fBmaildrop\fR(1)\fR\m[]\&\s-2\u[5]\d\s+2,
\m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2, \m[blue]\fB\fBmaildirquota\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fB\fBdeliverquota\fR(8)\fR\m[]\&\s-2\u[6]\d\s+2, \m[blue]\fB\fBdeliverquota\fR(8)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fB\fBmaildropfilter\fR(7)\fR\m[]\&\s-2\u[7]\d\s+2, \m[blue]\fB\fBmaildropfilter\fR(7)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBhttp://www\&.qmail\&.org/man/man5/maildir\&.html\fR\m[]\&. \m[blue]\fBhttp://www\&.qmail\&.org/man/man5/maildir\&.html\fR\m[]\&.
 End of changes. 9 change blocks. 
7 lines changed or deleted 357 lines changed or added

Home  |  About  |  Features  |  All  |  Newest  |  Dox  |  Diffs  |  RSS Feeds  |  Screenshots  |  Comments  |  Imprint  |  Privacy  |  HTTP(S)