added man pages

1 files changed, 138 insertions, 0 deletions

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)