From 923ac74f5de23d3a583ac3f0ba4a5e516947c259 Mon Sep 17 00:00:00 2001 From: Art Cancro Date: Fri, 26 Mar 2004 05:40:50 +0000 Subject: [PATCH] *** empty log message *** --- citadel/ChangeLog | 5 +- citadel/docs/citadel.html | 247 +++++++++++++++++++++++++++----------- 2 files changed, 180 insertions(+), 72 deletions(-) diff --git a/citadel/ChangeLog b/citadel/ChangeLog index 9c7b1fee8..525a924a3 100644 --- a/citadel/ChangeLog +++ b/citadel/ChangeLog @@ -1,4 +1,7 @@ $Log$ + Revision 614.102 2004/03/26 05:40:47 ajc + *** empty log message *** + Revision 614.101 2004/03/26 05:13:15 ajc * citadel-slapd.conf: comment out the reference to the Citadel schema and add "schemacheck off" to make it easier to get started with the @@ -5618,5 +5621,3 @@ Sat Jul 11 00:20:48 EDT 1998 Nathan Bryant Fri Jul 10 1998 Art Cancro * Initial CVS import - - diff --git a/citadel/docs/citadel.html b/citadel/docs/citadel.html index 2f6b1c78e..063100d58 100644 --- a/citadel/docs/citadel.html +++ b/citadel/docs/citadel.html @@ -214,13 +214,22 @@ interval your Citadel database
-
  • Cryptography support (TLS/SSL)
      • -
    1. Overview
      2. -
    2. Generating and installing a Trusted Certificate
      3. +
    3. Overview
      4. +
    4. Generating and installing a Trusted +Certificate
      5. +
    +
  • LDAP directory support
    • +
      +
    1. Introduction
      2. +
    2. Preparing +your LDAP server for Citadel connections
      +
      3. +
    3. Configuring the +LDAP Connector for Citadel
      +
    -
  • Included utilities
    1. Overview
      2. @@ -652,9 +661,11 @@ than telnet (such as ssh), you might want the telnet service to go straight into Citadel, instead of displaying the login: prompt first. You can do this by having telnetd start citadel directly instead of -/bin/login. The setup program will offer to configure +/bin/login. The setup program will offer to +configure this automatically for you if it sees a configuration it understands. -If you would prefer to configure it manually, all you need to do is make a +If you would prefer to configure it manually, all you need to do is +make a simple change to your inetd or xinetd configuration. Here are some configuration examples.

      An example for inetd (put the following line in /etc/inetd.conf, @@ -663,14 +674,17 @@ replacing any existing telnet configuration line already there):

      An example for xinetd (if you have a file called /etc/xinetd.d/telnet then simply replace that file with this one):

      service telnet
      {
      	flags           = REUSE
      	socket_type     = stream
      	wait            = no
      	user            = root
      	server          = /usr/sbin/in.telnetd
      	server_args     = -L /usr/local/citadel/citadel
      	log_on_failure  += USERID
      	disable         = no
      }
      -

      Please make sure you know what you're doing before you install this! If +

      Please make sure you know what you're doing before you install this! +If you are going to put Citadel somewhere other than /usr/local/citadel then change the directory name accordingly. If you know of any other local peculiarities which need to be observed, edit the above configuration accordingly as well. And, of course, if you're working remotely, make -sure you can successfully log in using SSH before you start making -changes to telnet, because if you accidentally break telnet and don't have +sure you can successfully log in using SSH before you start +making +changes to telnet, because if you accidentally break telnet and don't +have SSH running, you'll have effectively locked yourself out of your system until you can get physical access to the console.

      @@ -844,14 +858,19 @@ program against to set up some data files. If a directory is not specified, the directory name which was specified in the Makefile will be used.

      -xDebugLevel - Set the verbosity of trace messages printed. -When -x is used, it will suppress messages sent to syslog (see below). In -other words, syslog will never see certain messages if -x is used. Normally -you should configure logging through syslog, but -x may still be useful in -some circumstances. The available debugging levels are:

      +When -x is used, it will suppress messages sent to syslog (see below). +In +other words, syslog will never see certain messages if -x is used. +Normally +you should configure logging through syslog, but -x may still be useful +in +some circumstances. The available debugging levels are:

      • 0 - Emergency condition; Citadel will exit immediately
        • -
      • 1 - Severe errors; Citadel may be unable to continue without attention
        • -
      • 2 - Critical errors; Citadel will continue with degraded functionality
        • +
      • 1 - Severe errors; Citadel may be unable to continue without +attention
        • +
      • 2 - Critical errors; Citadel will continue with degraded +functionality
      • 3 - Error conditions; Citadel will recover and continue normally
      • 4 - Warning messages; Citadel will continue normally
      • 5 - Normal operational messages
        • @@ -860,14 +879,20 @@ some circumstances. The available debugging levels are:

      -tTraceFile - Tell the server where to send its debug/trace output. Normally it is sent to stdout.

      -

      -lLogFacility - Tell the server to send its debug/trace output -to the syslog service on the host system instead of to a -trace file. LogFacility must be one of: kern, user, mail, +

      -lLogFacility - Tell the server to send its debug/trace +output +to the syslog service on the host system instead of +to a +trace file. LogFacility must be one of: kern, user, +mail, daemon, auth, syslog, lpr, news, uucp, local0, local1, local2, local3, -local4, local5, local6, local7. Please note that use of the --l option will cancel any use of the -t option; that is, -if you specify a trace file and a syslog facility, log output will +local4, local5, local6, local7. Please note that use of the +-l option will cancel any use of the -t option; that +is, +if you specify a trace file and a syslog facility, log output +will only go to the syslog facility. +

      -d - Run as a daemon; i.e. in the background. This switch would be necessary if you were starting the Citadel server, for example, from an rc.local script (which is not recommended, because @@ -1616,12 +1641,7 @@ headers will never be altered.

      The final set of options configures system-wide defaults for the auto-purger:

      -
      Default user purge time (days) [120]: 
      
-Default room purge time (days) [30]: 
      
-System default message expire policy (? for list) [2]: 
      
-Keep how many messages online? [150]:
      
-Mailbox default message expire policy (? for list) [1]: 
      
-
      +
      Default user purge time (days) [120]: 

      Default room purge time (days) [30]: 

      System default message expire policy (? for list) [2]: 

      Keep how many messages online? [150]:

      Mailbox default message expire policy (? for list) [1]:

      Any user who does not log in for the period specified in 'Default user purge time' will be deleted the next time a purge is run. This setting may be modified on a per-user basis.

      @@ -1635,10 +1655,12 @@ messages are expired (purged) off the system. You can specify any of:

    2. Do not purge at all

      3. Again, this setting may be overridden on a per-floor basis, and the -floor setting may be overridden on a per-room basis. You'll also notice -that you can set a different default for mailbox rooms if you want -to. This can allow you, for example, to set a policy under which old -messages scroll out of public rooms, but private mail stays online indefinitely +floor setting may be overridden on a per-room basis. You'll also notice +that you can set a different default for mailbox rooms if you +want +to. This can allow you, for example, to set a policy under which old +messages scroll out of public rooms, but private mail stays online +indefinitely until deleted by the mailbox owners.

      Save this configuration? No

      When you're done, enter 'Yes' to confirm the changes, or 'No' to @@ -1848,7 +1870,7 @@ points of the configuration of Postfix or any other mailer, so refer to the documentation to those programs and keep in mind that Citadel has LMTP support.

      -

      For outbound mail, you +

      For outbound mail, you can either allow Citadel to perform deliveries directly (this won't affect your other mail system because outbound mail doesn't @@ -2208,54 +2230,139 @@ From the command line, you can do it with a command like:
      exported.dat at this time, or you might want to save it somewhere as a sort of pseudo-backup.

    -

    Cryptography support (TLS/SSL)

    - -

    Overview

    +

    Overview

    Citadel provides built-in support for encryption using Transport -Layer Security (TLS) for ESMTP, IMAP, POP3, and the Citadel client protocol. -A simple cryptographic configuration is installed automatically when you -bring the system online. The remainder of this section describes how this +Layer Security (TLS) for ESMTP, IMAP, POP3, and the Citadel client +protocol. +A simple cryptographic configuration is installed automatically when +you +bring the system online. The remainder of this section describes how +this configuration is built, and what you can do to make changes to it.

    -

    Encryption files are kept in the keys/ directory. The three -files used by Citadel are:

      -
    • citadel.key - Contains your system's RSA private key. Citadel -generates a new key automatically if one is not found. -
    • citadel.csr - Contains a Certificate Signing Request (CSR) -for your system. Citadel generates a new CSR automatically, using your -private key, if one is not found. -
    • citadel.cer - Contains the public certificate for your -system. The public key in the certificate must correspond with the +

      Encryption files are kept in the keys/ directory. The +three +files used by Citadel are:

      +
        +
      • citadel.key - Contains your system's RSA private key. +Citadel +generates a new key automatically if one is not found.
        • +
      • citadel.csr - Contains a Certificate Signing Request +(CSR) +for your system. Citadel generates a new CSR automatically, using your +private key, if one is not found.
        • +
      • citadel.cer - Contains the public certificate for your +system. The public key in the certificate must correspond with +the private key in citadel.key, otherwise encryption will not -function properly. Citadel will generate a self-signed certificate, again -using your private key, if a certificate is not found. -

      - -

      Generating and installing a Trusted Certificate

      +function properly. Citadel will generate a self-signed certificate, +again +using your private key, if a certificate is not found.
      • +
    +

    Generating and installing a Trusted +Certificate

    If you wish to interact with 3rd party clients -that have hard coded lists of acceptable Certificate Authorities, and you -do not want annoying dialog boxes popping up for the user on the first (or +that have hard coded lists of acceptable Certificate Authorities, and +you +do not want annoying dialog boxes popping up for the user on the first +(or all) connections, then you will have to have your key signed by a valid Certificate Authority.

    -

    It is beyond the scope of this document to provide a complete tutorial -on SSL certificates. Here are the general rules to follow:

      -
    • Generally, the Certificate Signing Requeste which is automatically -generated by Citadel will not contain enough information for any Certificate -Authority to sign it. Generate a new CSR with the following commands:
      -
      -cd keys
      -openssl req -new -key citadel.key -out citadel.csr
      -
      -Answer all questions (your geographic location, organization name, etc.) -and then send the new citadel.csr to your Certificate Authority -when you order the certificate. -
    • When the certificate is received, simply save it as citadel.cer -and restart the Citadel server. -

    - +

    It is beyond the scope of this document to provide a complete +tutorial +on SSL certificates. Here are the general rules to follow:

    +
      +
    • Generally, the Certificate Signing Requeste which is +automatically +generated by Citadel will not contain enough information for any +Certificate +Authority to sign it. Generate a new CSR with the following commands:
      +
      + cd keys
      + openssl req -new -key citadel.key -out citadel.csr
      +
      +Answer all questions (your geographic location, organization name, +etc.) +and then send the new citadel.csr to your Certificate +Authority +when you order the certificate.
      • +
    • When the certificate is received, simply save it as citadel.cer +and restart the Citadel server.
      • +
    +
    +
    +
    +

    LDAP (Directory) Support

    +
    +

    Introduction

    +LDAP (Lightweight Directory Access Protocol) has become the open +standard protocol for directory access.  There are many client +programs which are capable of making use of an LDAP directory +service.  Therefore it may be beneficial for some sites to have a +directory available which is populated with Citadel user information.
    +
    +Citadel does not contain its own LDAP service, because that would +eliminate its ability to coexist with any existing directory you may +already have in place at your organization.  Instead, we provide +the LDAP Connector for Citadel, which allows the Citadel service to +populate an external LDAP directory.  If you do not already have +an LDAP directory in place, you can use the OpenLDAP server, which is +probably already present in your operating system, or at least can be +loaded from the installation CD's.  The supplied configuration +file citadel-slapd.conf can be used as a starting +point to get your LDAP server running.
    +
    +

    Preparing your +LDAP server for Citadel connections

    +It is difficult to find a commonly accepted LDAP scheme. It seems, most +real life LDAP installations go for the domain oriented apporach +and lay out the structure after an existing domain/subdomain structure. +

    The most widely accepted and standardized object for storing +personal data +clearly is "inetOrgPerson".  Citadel therefore attempts to follow +this type of schema.
    +

    +

    If you are using OpenLDAP as your directory server, you should +choose options similar to the following:
    +

    +
    database        ldbm
    schemacheck     off
    allow           bind_v2
    suffix          "dc=servername,dc=domain,dc=org"
    rootdn          "cn=manager,dc=servername,dc=domain,dc=org"
    rootpw          secret
    +
      +
    • Obviously, you can make your suffix and rootdn whatever you wish, +but in most cases you'd simply follow a DC path that looks similar to +your DNS domain.
      • +
    • If you don't want LDBM, feel free to choose any backend available +on your system.
      • +
    • bind_v2 is required because Citadel will make +v2 protocol connections.
      • +
    • schemacheck off is recommended because Citadel uses +fields that do not necessarily exist in your system's default +schema.  If you don't like that idea, your other option is to +reference the included citadel-openldap.schema +in your configuration.
      • +
    • Your rootdn and rootpw can be whatever you +want.  Usually the rootdn is cn=manager, +followed by your usual suffix.  Please don't use secret as your password, as in +this example.  Select a new password for your site.
      • +
    +
    +Your LDAP service must be up +and running before you attempt to connect Citadel to it.
    +
    +

    Configuring the +LDAP Connector for Citadel

    +FIXME   finish writing this
    +
    +
    +
    +
    +

    Utilities

    -- 2.39.2