added man pages

7 files changed, 510 insertions, 0 deletions

diff --git a/man/Makefile b/man/Makefile
new file mode 100644
index 0000000..0eb2e57
--- /dev/null
+++ b/man/Makefile
@@ -0,0 +1,47 @@
+# Don't edit Makefile! Use conf-* for configuration.
+
+SHELL=/bin/sh
+
+default: man
+
+bincimap.0: \
+bincimap.1
+	nroff -man bincimap.1 > bincimap.0
+
+bincimap.1: \
+bincimap.9 ../conf-qmail
+	cat bincimap.9 \
+	| sed s}SQMAIL}"`head -1 ../conf-qmail`"}g \
+	> bincimap.1 
+
+bincimapd.0: \
+bincimapd.1
+	nroff -man bincimapd.1 > bincimapd.0
+
+bincimapd.1: \
+bincimapd.9 ../conf-qmail
+	cat bincimapd.9 \
+	| sed s}SQMAIL}"`head -1 ../conf-qmail`"}g \
+	> bincimapd.1
+
+bincimap-up.0: \
+bincimap-up.1
+	nroff -man bincimap-up.1 > bincimap-up.0
+
+bincimap-up.1: \
+bincimap-up.9 ../conf-qmail
+	cat bincimap-up.9 \
+	| sed s}SQMAIL}"`head -1 ../conf-qmail`"}g \
+	> bincimap-up.1 
+
+bincimap-updatecache.0: \
+bincimap-updatecache.7
+	nroff -man bincimap-updatecache.7 > bincimap-updatecache.0
+
+clean: \
+TARGETS
+	rm -f `cat TARGETS`
+
+man: \
+bincimap.0 bincimapd.0 bincimap-up.0 \
+bincimap-updatecache.0
diff --git a/man/Makefile.mandoc b/man/Makefile.mandoc
new file mode 100644
index 0000000..a54789e
--- /dev/null
+++ b/man/Makefile.mandoc
@@ -0,0 +1,47 @@
+#Don't edit Makefile! Use conf-* for configuration.
+
+SHELL=/bin/sh
+
+default: man
+
+bincimap.0: \
+bincimap.1
+	mandoc -man bincimap.1 > bincimap.0
+
+bincimap.1: \
+bincimap.9 ../conf-qmail
+	cat bincimap.9 \
+	| sed s}SQMAIL}"`head -1 ../conf-qmail`"}g \
+	> bincimap.1 
+
+bincimapd.0: \
+bincimapd.1
+	mandoc -man bincimapd.1 > bincimapd.0
+
+bincimapd.1: \
+bincimapd.9 ../conf-qmail
+	cat bincimapd.9 \
+	| sed s}SQMAIL}"`head -1 ../conf-qmail`"}g \
+	> bincimapd.1
+
+bincimap-up.0: \
+bincimap-up.1
+	mandoc -man bincimap-up.1 > bincimap-up.0
+
+bincimap-up.1: \
+bincimap-up.9 ../conf-qmail
+	cat bincimap-up.9 \
+	| sed s}SQMAIL}"`head -1 ../conf-qmail`"}g \
+	> bincimap-up.1 
+
+bincimap-updatecache.0: \
+bincimap-updatecache.7
+	mandoc -man bincimap-updatecache.7 > bincimap-updatecache.0
+
+clean: \
+TARGETS
+	rm -f `cat TARGETS`
+
+man: \
+bincimap.0 bincimapd.0 bincimap-up.0 \
+bincimap-updatecache.0
diff --git a/man/TARGETS b/man/TARGETS
new file mode 100644
index 0000000..617e875
--- /dev/null
+++ b/man/TARGETS
@@ -0,0 +1,7 @@
+bincimap.0
+bincimap.1
+bincimapd.0
+bincimapd.1
+bincimap-up.0
+bincimap-up.1
+bincimap-updatecache.0
diff --git a/man/bincimap-up.9 b/man/bincimap-up.9
new file mode 100644
index 0000000..431f0a1
--- /dev/null
+++ b/man/bincimap-up.9
@@ -0,0 +1,138 @@
+.TH bincimap-up  1
+.SH "NAME"
+bincimap-up \- IMAP server stub
+.SH "SYNOPSIS"
+.B bincimap-up [options] -- <authenticator> bincimapd <maildepot>
+
+.B bincimap-up -- SQMAIL/bin/qmail-authuser bincimapd Maildir
+
+.SH "DESCRIPTION"
+.B bincimap-up 
+is a pre-authentication IMAP server typically invoked by 
+.B sslserver 
+providing encrypted IMAPS and IMAP/StartTLS connections; though
+.B tcpserver
+could be used for un-encrypted IMAP services as well.
+Since it includes only limited IMAP capabilities, it is a 
+.I stub 
+IMAP server only.
+.SH "CONFIGURATION"
+.B bincimap-up 
+uses the environment for reading its settings, typically given by
+.B envdir
+in the directory
+.I env 
+as files with one line als content. 
+Some environment variables can be overwritten with command line options. 
+
+In the following samples, the environment variable (including possible 
+settings) is  shown left and their potential command line option is
+given right after the '|' symbol.
+.TP
+\fBBINCIMAP_LOGIN\fR=PLAIN+LOGIN
+includes the authentication methodes advertised. Its setting
+is mandatory. The default is \fIPLAIN+LOGIN\fR; 
+though \fIPLAIN+LOGIN+CRAM-MD5\fR is honored 
+and the \fIchallenge\fR is generated and deployed for verification. 
+The method \fICRAM-MD5\fR requires 
+access to the unencrypted passwords.
+.TP
+\fBALLOW_NONSSL_PLAINTEXT_LOGINS\fR=yes | \fB\-a, \-\-allow-plain\fR 
+If this setting is enabled, Binc IMAP will permit plain text
+authentication for unencrypted (SSL/TLS) IMAP sessions. This is
+considered unsafe unless the server is run on a private switched
+network. By default, plain text authentication is disabled for
+unencrypted sessions.
+.TP
+\fBSHOW_VERSION_IN_GREETING\fR=yes | \fB\-v, \-\-show-version\fR 
+If this setting is enabled, Binc IMAP will expose its version string
+in the greeting presented to every connecting client. This is
+considered unsafe unless the server is run on a private switched
+network, because it eases the job of malicious users who exploit
+vulnerabilities in specific versions. By default, the version is not
+exposed in the server's greeting.
+.TP
+\fBLOG_TYPE\fR=[multilog|syslog] | \fB\-l\fR[...], \-\-\fBlog-type=\fR[...]
+This setting toggles which method Binc IMAP should use for
+logging. \fBsyslog\fR means to connect to syslog. \fBmultilog\fR means
+to log to stderr(2) and typically used together with the \fBmultilog\fR
+utility. 
+For daemontools/supervise, use \fBmultilog\fR. Default: \fBmultilog\fR.
+.TP
+\fBLOG_USER\fR=LOG_MAIL 
+is the syslog user name for loging. Default: \fILOG_DAEMON\fR. 
+Additionally, you can setup up to eight local tags for the syslog facility
+employing the environment variables \fBLOG_LOCAL0\fR to \fBLOG_LOCAL7\fB.
+.TP
+\fBDEPOT\fR=[Maildir++|IMAPdir] | \fB\-d=\fR[...], \fB\-\-depot=\fR[...]
+This setting sets whether to use a \fIMaildir++\fR or an \fIIMAPdir\fR
+depot. By default, the \fIMaildir++\fR depot is used. 
+.TP
+\fBDELIMITER\fR=<char> | \fB\-D\fR<char>, \fB\-\-delimiter\fR<char>
+This setting sets the mailbox hierarchy delimiter. 
+By default, Binc IMAP uses '\fI/\fR' as the delimiter (i.e., a/b/c). 
+When porting from servers that use a different delimiter, 
+certain clients may protest if the delimiter changes. For example, 
+Courier-IMAP uses '.' as its
+delimiter, and certain Mozilla/Thunderbird clients have problems
+dealing with a client using a different delimiter. 
+Set this options to '.' to work around the problem. 
+.TP
+\fB\-\-\fR
+Marks the end of options to
+.B bincimap-up.
+After this comes the checkpassword compatible authenticator.
+Note that it is essential that the authenticator invoked by
+.B bincimap-up 
+does not clear the environment and sets the value for \fI$USER\fR correctly.
+.TP
+\fB(trailing arguments)\fR
+Binc IMAP's authenticator. The first argument is invoked as an
+authenticator subprocess of \fBbincimap-up\fR, with the rest of the arguments
+passed as the authenticator's local arguments.
+.SH "ADDITIONAL ARGUMENTS"
+.B bincimap-up
+understands the following command line arguments upon call:
+.TP
+\fB\-h, -?, \-\-help\fR
+This option is passed to display basic usage on the command line.
+.TP
+\fB\-\-version\fR
+The option is passed to show the version number of the server on the
+command line.
+.SH "DIAGNOSTICS"
+.B bincimap-up
+and also 
+.B bincimapd
+recognize the setting of the environment variable:
+.TP
+\fBPROTOCOLDUMP\fR=yes
+to record the IMAP session's commands under
+.I /tmp/bincimap-dump-<number>-<client-ip>-<random>
+for interrogating the command flow.
+Upon compile time, further informations can be 
+invoked, which enable to diagnose 
+.BR bincimap 's
+behaviour, which can be found in the adjacent documentation.
+.SH "COPYRIGHT"
+Copyright (C) 2002-2005 Andreas Aardal Hanssen, 2023 Erwin Hoffmann
+
+This is free software; see the LICENSE for copying conditions. 
+There is NO warranty.
+.SH "LOGGING" 
+For every connection,
+.B bincimap-up 
+displays the current
+.I PID 
+and connecting 
+.IR IP .
+After the user issued a logout 
+or was disconnected, it records 
+for this IMAP session the number of 
+bytes 
+.I Read:\ n 
+and those which was 
+.IR Written:\ m .
+.SH "SEE ALSO"
+multilog(8), supervise(8), tcpserver(1), sslserver(1),
+bincimap(1), bincimapd(1), qmail-authuser(8)
diff --git a/man/bincimap-updatecache.7 b/man/bincimap-updatecache.7
new file mode 100644
index 0000000..66f71b2
--- /dev/null
+++ b/man/bincimap-updatecache.7
@@ -0,0 +1,57 @@
+.TH bincimap-udatecache 7
+.SH "NAME"
+bincimap-updatecache 
+.SH "SYNOPSIS"
+.B bincimap-updatecache <maildir>
+.SH "DESCRIPTION"
+.B bincimap-updatecache
+reads the messages available at
+.I <maildir> 
+and re-generates the
+.I binc-cache
+file in this directory.
+.SH "INVOCATION"
+.B bincimap-updatecache 
+is called by the owner of the
+.IR <maildepot> .
+Given the Maildir++ format, a
+.I <maildir> 
+is either
+.I Maildir
+or one of the sub-directories indicated via a dot:
+.IR .submaildir .
+Instead of nested subdirectories, 
+.I .submaildir 
+ist just the first level <maildir>. Nesting is
+realized by concatination of <maildir> names with a dot.
+
+.B bincimap-updatecache
+generates the file
+.I bincimap-cache
+for only this sub-directory given by its path name:
+
+.EX
+  \fBbincimap-updatecache\fR Maildir/.maildirname
+.EE
+
+.B bincimap-updatecache
+considers by default the
+.I Maildir++
+format, including the
+.IR new , 
+.IR cur , 
+and
+.I tmp
+sub-directories.
+In case the 
+.I <maildepot>
+is given as
+.I IMAPdir 
+.BR bincimap-updatecache ,
+requires the setting of
+.I DEPOT=IMAPdir 
+as exported environment variable.
+.SH "COPYRIGHT"
+Copyright (C) 2023 Erwin Hoffmann
+.SH "SEE ALSO"
+bincimap(1), bincimap-up(1), bincimapd(1)
diff --git a/man/bincimap.9 b/man/bincimap.9
new file mode 100644
index 0000000..64940ff
--- /dev/null
+++ b/man/bincimap.9
@@ -0,0 +1,66 @@
+.TH bincimap 1
+.SH "NAME"
+bincimap \- IMAP server
+.SH "SYNOPSIS"
+.B bincimap-up [options] -- <authenticator> bincimapd <maildepot>
+
+.B bincimap-up -- SQMAIL/bin/qmail-authuser bincimapd Maildir
+.SH "DESCRIPTION"
+Binc IMAP is an IMAP server for Maildir type mailboxes. It is well
+known for being easy to install, use and maintain.
+
+Binc IMAP is invoked by 
+.B sslserver
+in order to achieve TLS and/or StartTLS capabilities for the required
+confidentiality.
+
+Binc IMAP is unique because of its simple, yet powerful \fBinvocation
+pipeline\fR. This simple system makes it easy to have Binc IMAP do
+exactly what you want.
+
+The \fBinvocation pipeline\fR consists of the following parts:
+.TP 4
+.B bincimap-up
+Is a stub to start the IMAP session, configuring the service
+options, calling the authenticator, and finally invoking the 
+.B bincimapd 
+server.
+.TP 4
+.B qmail-authuser
+is the versatile PAM communicating with different user authentication
+backends and setting up the required 
+.I USER
+envrionment variable. Other PAMs, like
+.B checkpassword.pl
+can be used instead.
+.TP 4
+.B bincimapd 
+implements the IMAP interface to the user's 
+.I <maildepot>
+by name which could be a
+.I Maildir++
+or 
+.I IMAPdir 
+structured.
+.SH "COPYRIGHT"
+Copyright (C) 2002-2005 Andreas Aardal Hanssen, 2023 Erwin Hoffmann
+
+This is free software; see the LICENSE for copying conditions. There is
+NO warranty.
+.SH "NOTE"
+Please report any bugs to the
+.B Binc IMAP
+mailing list. Before posting your bug, check out the
+.B Binc IMAP
+official home page for a list of mailing list archives
+to browse.
+
+.RS
+.nf
+Mailing list: <binc@mail.fehcom.net>
+
+Subscribing to a mailing list: <binc-subscribe@mail.fehcom.net>
+Home page: https://www.fehcom.de/binc/bincimap.html
+.SH "SEE ALSO"
+bincimap-up(1), bincimapd(1), qmail-authuser(8),
+sslserver(1), tcpserver(1), multilog(1)
diff --git a/man/bincimapd.9 b/man/bincimapd.9
new file mode 100644
index 0000000..5e42551
--- /dev/null
+++ b/man/bincimapd.9
@@ -0,0 +1,148 @@
+.TH bincimapd 1
+.SH "NAME"
+bincimapd \- IMAP4rev1 server
+.SH "SYNOPSIS"
+.B bincimap-up [options] -- <authenticator> bincimapd <maildepot>
+
+.B bincimap-up -- SQMAIL/bin/qmail-authuser bincimapd Maildir
+.SH "DESCRIPTION"
+.B bincimapd 
+implements the IMAP interface to the user's 
+.I <maildepot>
+by name which could be
+.I Maildir++
+or 
+.I IMAPdir 
+structured.
+Upon invocation
+.B bincimapd
+switches to the home directory available by the user environment 
+and performs the commanded IMAP operations on the given
+.IR <maildepot> .
+.SH "CONFIGURATION"
+.B bincimapd
+shares the same environment variables with
+.BR bincimap-up ,
+thus there is no specific configuration required and therefore
+.I [...]
+is usually avoided, except for
+its first unqualified argument containing the name of the 
+mailbox depository in which
+.B bincimapd 
+should search for folders. If unset, some authenticators like
+.B qmail-authuser
+and 
+.B vmailmgr
+will fail. However, 
+.B bincimapd 
+runs in the environment of the user and honors the
+a specific setting of environment variables to cope 
+local preferences.
+.SH "COMPLIANCE"
+.B bincimapd
+conforms partially to IMAP4rev1 (RFCs 3501, 2177 [Idle], 2341 [Namespace], 
+2971 [Id]).
+Alphabetic list of supported IMAP commands:
+.IP \[bu] 2
+Append
+.IP \[bu] 2 
+Authenticate
+.IP \[bu] 2 
+Capability
+.IP \[bu] 2 
+Check
+.IP \[bu] 2 
+Close
+.IP \[bu] 2 
+Copy
+.IP \[bu] 2 
+Create
+.IP \[bu] 2 
+Delete
+.IP \[bu] 2 
+Examine
+.IP \[bu] 2 
+Expunge
+.IP \[bu] 2 
+Fetch
+.IP \[bu] 2 
+Id
+.IP \[bu] 2 
+Idle
+.IP \[bu] 2 
+List
+.IP \[bu] 2 
+Login
+.IP \[bu] 2 
+Logout
+.IP \[bu] 2 
+Lsub
+.IP \[bu] 2 
+Namespace
+.IP \[bu] 2 
+Noop
+.IP \[bu] 2 
+Rename
+.IP \[bu] 2 
+Search
+.IP \[bu] 2 
+Select
+.IP \[bu] 2 
+Starttls
+.IP \[bu] 2 
+Status
+.IP \[bu] 2 
+Store
+.IP \[bu] 2 
+Subscribe
+.IP \[bu] 2 
+Unsubscribe
+.SH "FILES"
+Within every
+.I <maildepot>
+subdirectory
+.B bincimpad
+generates a set of files 
+.TP
+.I $HOME/<maildepot>/.../bincimap-uidvalidity
+This file contains a version number, the
+.BR UIDNEXT ,
+and
+.B UIDVALIDITY
+values for the given mailbox.
+.TP
+.I $HOME/<maildepot>/.../bincimap-cache
+This file contains a version number, and it stores the
+.B UID
+values for each message, along with (optionally) some cached
+information.
+
+.RE
+Exception:
+.TP  
+.I $HOME/<maildepot>/.subscribed
+All subscribed <mailboxes> are included here. 
+.SH "LOGGING" 
+After the user login
+.B bincimapd 
+displays the 
+.IR PID , 
+.IR userid , 
+and
+.I IP address.
+On logout or disconnect
+it provides the 
+.IR PID ,
+the number of messages fetched
+.IR Bodies:\ n , 
+and the number of IMAP commands executed
+.IR Statements:\ m . 
+.SH "COPYRIGHT"
+Copyright (C) 2002-2005 Andreas Aardal Hanssen, 2023 Erwin Hoffmann
+
+This is free software; see the LICENSE for copying conditions. 
+There is NO warranty.
+.SH "SEE ALSO"
+bincimap(1), bincimap-up(1),
+multilog(8), supervise(8), tcpserver(1), sslserver(1),
+qmail-authuser(7)