Skip to main content

IBM Systems  >   z Systems  >   z/VM  >  

VM IMAP Beta Release 1.6.1 Installation

IMPORTANT NOTE: The index structure used by Beta Release 1.6 and higher is not compatible with the index structure used by earlier beta levels. If you were running a level of the IMAP server prior to Beta Release 1.5, you MUST delete and re-enroll all users so that they will end up with the new index structure. If you're running level 1.5 you can either delete and re-enroll all users or you can use the IMAP5TO6 sample exec to convert their existing indexes in the mailstore to the new format. Don't forget - if you choose to change index formats by deleting and re-enrolling users, deleting a user causes all their existing mail and folders to be removed from the mailstore.
1)  SETTING UP THE IMAP SERVER VIRTUAL MACHINE:
    -------------------------------------------
 
    - minimum system requirements
 
       o  VM 2.3.0, CMS14, TCP/IP 310
       o  LE 1.8
       o  SMTP APAR PQ31576 required
       o  SMTP APAR PQ41591 recommended
       o  CMS APAR VM61477 recommended
       o  CMS APAR VM62318 recommended
       o  CMS APAR VM61821 and TCPIP APAR PQ17871
          only required if you want to use a translate table
          other than the default one (note - you should also
          review PQ26583 and PQ31152)
       o  CMS APAR VM62679 recommended
       o  CP APAR VM62662 recommended
 
    - requires an "IUCV *SPL" directory statement to allow the server
      to connect to the *SPL system service in order to asynchronously
      read in mail as it arrives in the server's reader
 
    - requires an "IUCV ANY" (or an "IUCV sfs_server_id") directory
      statement to allow it to connect to the Mailstore SFS server
      (the IMAP server also must have SFS admin authority to the
      SFS filepool)
 
       Note:  This directory statement for the IMAP server will
              allow it to connect to the SFS server as opposed to
              the usual method of having an IUCV ALLOW statement in
              the SFS server's directory.  This is necessary because
              we do not want IMAP users able to directly connect to
              the SFS server and corrupt the directory structure or
              the data residing in the filepool.  If you have other
              users that will need to access the SFS server (eg:
              backup machines) you will need to add an
              IUCV sfs_server_id to their directory entries too.
 
    - requires an "IUCV ALLOW" to enable the IMAP server for incoming
      APPC/VM conversations which will be initiated by any IMAP
      administrators that have been specified in the CMS private
      resource registration file on the IMAP server's A disk and which
      use the queue-based administrative interface that is provided
      in the IMAP SAMPEXEC
 
    - requires an "OPTION MAXCONN 2000" directory statement
      to allow up to 2000 IUCV connections to the SFS server.
 
    - if running with AUTHENTICATE CP, requires privilege class B
      in order to issue DIAG 84 to validate passwords.  If running
      with AUTHENTICATE ESM, this may not be required, but some
      authorizations will need to be configured on the ESM.
 
    - sample IMAP server directory entry might look like:
      USER IMAP XXXXXXXX 128M 256M BG
         ACCOUNT XXX
         ACIGROUP SERVER
         IUCV ALLOW
         IUCV ANY
         IUCV *SPL
         MACHINE XC
         OPTION MAXCONN 2000 QUICKDSP
         IPL CMS PARM AUTOCR
         CONSOLE 0009 3215 T
         SPOOL 000C 2540 READER *
         SPOOL 000D 2540 PUNCH A
         SPOOL 000E 1403 A
         LINK MAINT 0190 0190 RR
         LINK MAINT 019E 019E RR
         LINK TCPMAINT 0592 0592 RR
         MDISK 0191 3390 3316 2 K1E41A MR
 
    - requires a $SERVER$ NAMES file (private resource registration
      file) on an accessed disk with the following VMIPC entry to
      list any virtual machines that will be using the queue-based
      administrative interface (IMAP SAMPEXEC) to issue commands to
      the IMAP server (such as ENROLL USERID):
 
                 +---------------------------------+
                 |  :nick.VMIPC                    |
                 |    :list.user1 user2 user3 ...  |
                 +---------------------------------+
 
    - requires an IMAP CONFIG file (userid CONFIG is also
      allowed) on an accessed disk which specifies
      configuration information for the IMAP server (FILEPOOLID and
      BADFILEID are required IMAP configuration file statements to
      specify the filepool id of the mailstore and the userid to which
      bad mail files should be sent, if these are not configured
      the server will not start).
 
      The following are the currently supported statements that can
      be specified in the IMAP CONFIG file:
 
       FILEPOOLID userid        - userid of the SFS server containing
                                  IMAP's mailstore.  No default.
       BADFILEID userid         - userid to whom reader files are
                                  transferred when the IMAP server has
                                  difficulty delivering them.  No
                                  default.
       MAILORIGINID userid ...  - userids from whom mail arriving in the
                                  reader must originate.  Default is
                                  obtained from the TCPIP DATA file.
                                  If not present in the TCPIP DATA
                                  file, defaults to SMTP.  Up to 32
                                  userids may be listed.
       TRACE ALL                - turns all tracing on (CODEFLOW,
                                  SOCKLIBCALLS, and SOCKETIO).
       TRACE CODEFLOW           - turns module entry/exit tracing
                                  on.
       TRACE SOCKLIBCALLS       - turns socket library call tracing
                                  on.
       TRACE SOCKETIO [ipaddr]  - turns tracing of all data sent
                                  or received on a socket on.
                                  If an IP address is given, only
                                  sockets active from that IP address
                                  will be displayed.
       AUTHENTICATE CP|ESM      - whether userids should be
                                  authenticated by CP (the directory)
                                  or by an external security manager.
                                  Default is CP.
       PORT integer             - TCP port number on which the IMAP
                                  server will listen.  If omitted IMAP
                                  listens on port 143.
       READERTHREADS integer    - number of threads to create to
                                  handle incoming reader files.
                                  Default is 1 thread.
       IDLETIMEOUT integer integer - first integer is the amount of
                                     time (in seconds) that an
                                     unauthenticated connection can
                                     be idle (have no activity).  The
                                     second integer is the amount of
                                     time (in seconds) that an
                                     authenticated connection can be
                                     be idle.  Default values are
                                     60 and 0 (0 means infinity).
                                     RFC 2060 section 5.4 restricts
                                     the second number to a minimum
                                     of 1800 (30 minutes).
       ENROLLDEFAULTS integer integer - first integer is the number of
                                         blocks to allocate for a
                                         user if no value is provided
                                         on the ENROLL command.  The
                                         second number is the storage
                                         group the user should be
                                         enrolled in.  Defaults are
                                         100 and 2 respectively.
 
      Blank lines are allowed, and comment lines must begin with
      a semicolon.
 
    - the PROFILE EXEC for the IMAP server should be updated to activate
      the C runtime library (GLOBAL LOADLIB SCEERUN), and (optionally)
      to start up the IMAP server (IMAPMAIN MODULE)
 
    - to provide a custom translate table follow the directions in
      the TCPIP documentation for creating a TCPXLBIN file (or
      copy an existing file with the desired translation).  The
      IMAP server follows the standard hierarchy for translation
      tables.  It first looks for IMAP TCPXLBIN, if that is not
      found it looks for STANDARD TCPXLBIN.  Lastly if neither
      are found it uses a hardcoded translate table that is
      adequate for most purposes.  It is strongly recommended
      that IMAP be configured to use the same translation table
      as SMTP is using.
 
 
2)  SETTING UP THE MAILSTORE SFS SERVER VIRTUAL MACHINE:
    ----------------------------------------------------
 
    - we strongly recommend a dedicated SFS server be used as
      the IMAP mailstore.  For details on setup and configuring
      an SFS filepool please refer to the Filepool Planning,
      Administration and Operation manual for your VM release.
      What we're documenting here are the differences from
      a "normal" filepool setup.
 
    - requires an "IUCV *IDENT" directory statement to identify
      itself as a resource owner, but no "IUCV ALLOW" since we do
      not want enrolled user's to be able to connect to the server
      and corrupt the directory structure or the data residing in
      the filepool
 
    - requires an "OPTION MAXCONN 2000 APPLMON" directory statement
      to allow up to 2000 APPC connections to the server.  One
      APPC connection is used for each active user.  2000 is a
      reasonable initial default.  If you expect to have more than
      2000 concurrent users you should adjust it upward to match
      the expected number of users.  This number should be the
      same for the IMAP server and the IMAP mailstore.
 
    - make sure that the IMAP server virtual machine has SFS admin
      authority for the filepool
 
    - sample IMAP mailstore SFS server directory entry might
      look like:
 
       USER IMAPSFS XXXXXXXX 128M 512M G
         ACCOUNT G28G GXX/BOX 002
         ACIGROUP SERVER
         IUCV *IDENT RESANY GLOBAL REVOKE
         MACHINE XC
         OPTION MAXCONN 2000 APPLMON QUICKDSP
         IPL CMS PARM AUTOCR
         CONSOLE 0009 3215 T
         SPOOL 000C 2540 READER *
         SPOOL 000D 2540 PUNCH A
         SPOOL 000E 1403 A
         LINK MAINT 0190 0190 RR
         LINK MAINT 019D 019D RR
         LINK MAINT 019E 019E RR
         MDISK 0191 3390 3336 1 K1E419 MR
         MDISK 0301 3390 2906 ? K1E400 MR
         MDISK 0302 3390 3336 ? K1E400 MR
         MDISK 0303 3390 3337 ? K1E400 MR
         MDISK 0304 3390 3338 ? K1E400 MR
         MDISK 0305 3390 3336 ? K1E418 MR
 
 
 
3)  SETTING UP ANY IMAP ADMINISTRATIVE VIRTUAL MACHINES:
    ----------------------------------------------------
 
    - an administrative virtual machine will be used to enroll and
      delete users in the IMAP Mailstore as well as issue other
      administrator commands (eg: shutdown the server, set an alert,
      etc.).  This may be the systems programmer's personal id or
      someone else's id or an id purposely created for IMAP
      administration.
 
    - make sure that the administrator userid(s) are specified in the
      private resource registration file ($SERVER$ NAMES) on the
      IMAP server virtual machine.  Keep in mind that each userid
      listed in $SERVER$ NAMES has access to the full suite of
      administrator commands and can DELETE users, shut the server
      down, or in other ways cause havoc.
 
    - requires the IMAP SAMPEXEC to communicate with the IMAP server
      using the queue-based administrative interface
 
    - IMAP SAMPEXEC should be renamed to have a filename matching the
      IMAP server virtual machine userid, a filetype of exec and
      then must reside on an accessed disk so that the administer can
      run the exec to issue administrative commands
 
       Example:  For an IMAP server with a userid of IMAP, the exec
                 would be renamed to IMAP EXEC and "IMAP ENROLL SMITH"
                 would enroll userid SMITH into the IMAP mailstore.
 
    - the following are the currently implemented administrator
      commands:
 
       ALERT [optional text]
        If no text is supplied then the current alert is cleared.
        If text is supplied it becomes the alert text that will
        be forwarded to each client on their next transaction.
 
       CP command
        The specified command is passed UNCHANGED (it is
        not uppercased for example) to CP for execution via
        a DIAGnose 08.  The command's return code is returned.
        This is useful for spooling console closed, etc..
 
       DELETE userid
        Un-enroll the specified userid
 
       ENROLL userid [blocks [storage_group]]
        Enroll a userid in the mailstore, optionally an initial
        block allocation and storage group can be specified.
        If omitted, their values default to those specified
        on EnrollDefaults in the config file.
 
       HELP
        Returns a list of supported commands
 
       MODIFY userid +/-blocks
        Increase or decrease the number of blocks a user is
        authorised to consume in the mailstore.
 
       SHAREFOLDER to_user foldername owning_user foldername
        This adds an entry in the to user's mailbox index table
        for a folder with foldername.  The entry actually points
        to owning_user's folder (see usage note below).
 
       SHUTDOWN
        Shut down the IMAP server
 
       STARTRDR
        Start an additional thread to process reader files.
 
       STATS [RESET]
        Return a list of server statistic counters, and optionally
        reset the counters.
 
       TRACE ALL|CODEFLOW|SOCKLIBCALLS|SOCKETIO [ipaddr] [ON|OFF]
        TRACE ALL [ON] turns on all (codeflow, socklibcalls and
        socketio (for all IP addresses)) tracing.  TRACE ALL OFF
        turns off all (codeflow, socklibcalls and socketio)
        tracing.  TRACE CODEFLOW [ON] turns on just module entry and
        exit tracing.  TRACE CODEFLOW OFF turns off module entry and
        exit tracing.  TRACE SOCKETIO [ON] turns on display of all
        data sent and received on a socket.  You can optionally
        specify an IP address.  Only sockets active from that IP
        address will have their socket data displayed.  TRACE
        SOCKETIO OFF turns off socket I/O tracing.  TRACE
        SOCKLIBCALLS [ON] traces each socket library call.  TRACE
        SOCKLIBCALLS OFF turns off socket library call tracing.
 
    - the needed SFS authorities must be in place before issuing
      the SHAREFOLDER command.  The folder owner must have
      granted read access to their MAILBOX INDEX file in their
      highest level directory and also read access to each file
      in the directory being shared.  SHAREFOLDER does not attempt
      to issue the needed grant commands because there are a
      number of SFS ESMs each of which handles the granting of
      authorities in their own way.  If you would find an exit
      useful at this point (so the granting may be automated)
      please let us know.
 
 
4)  CONFIGURING THE SMTP MACHINE TO ROUTE MAIL TO THE IMAP SERVER:
    --------------------------------------------------------------
 
    In general we recommend a dedicated SMTP server for use with
    IMAP.  This does not require a dedicated stack, since you can
    use multihoming support.  However you must be at FL 320 before
    the multihoming support works with SMTP.  We do have beta
    customers running on FL 310, using the command exit on their
    primary SMTP (with FL 310 and FL 320) or not using our IMAPCMDX
    at all since they run with a mailer (they have developed similar
    function for use with their mailer (IMAP determines who the mail
    is destined for by examining netdata text unit INMTUID (x1002),
    the important thing is that it be set correctly)).  So the
    recommendation to use a dedicated server is flexible.
 
    - if you are not calling your IMAP server IMAP you must edit
      IMAPCMDX and update the servername variable (while in there,
      verify the at sign character is defined as expected for
      your code page (generally only a concern in Scandinavia))
 
    - place the IMAPCMDX EXEC and IMAP123 REXX files on SMTP's
      191 (or somewhere in it's access order, eg: TCPMAINT's 198)
 
    - in order to have mail sent to the IMAP mailstore, the SMTP
      virtual machine must be configured to send local mail to
      the IMAP virtual machine.  This is done using the command
      exit for the PUNCH command.  Add the following to your
      SMTP's config:
 
        SMTPCMDS
          EXIT IMAPCMDX EXEC FOR PUNCH ON
        ENDSMTPCMDS
 
    - this will cause SMTP to call our exit which will send a
      file over to the IMAP virtual machine whenever local
      mail arrives
 
    - the IMAP virtual machine will determine if the mail is for a
      registered IMAP user and automatically place it in the INBOX
      for that user (if it is not for a registered IMAP user, then
      it will transfer it directly to the user)
 
 
 
5)  STARTING UP THE IMAP SERVER:
    ----------------------------
    - once all of the appropriate setup work has taken place, start
      the IMAP server by invoking the IMAPMAIN MODULE from the
      command line or profile of the IMAP server virtual machine
 
    - IMAPMAIN performs the following:
 
       -- read and process the configuration information from the
          configuration file (it first looks for a serverid CONFIG *
          file, if that is not found it looks for an IMAP CONFIG *
          file)
       -- create a thread to process console input
       -- create a thread to process mail arriving through the spool
       -- create a thread to handle administration requests
       -- create a thread to listen for new connections on the IMAP
          port (this thread will create an additional thread for
          every new client connection to the server)
 
 
 
6)  ENROLLING IMAP USERS:
    ---------------------
 
    - when the IMAP server is up and running, the administrative
      interface is used to enroll new users
 
    - from an administrative virtual machine, invoke the sample exec
      (which has been renamed from IMAP SAMPEXEC to the name of the
      IMAP server with filetype exec) to enroll a user
         eg: IMAP ENROLL SMITH
 
    - this will cause the IMAP server to perform the following:
 
       -- enroll the userid in the SFS filepool
       -- create an INBOX directory for the user
       -- create the MAILBOX INDEX file in the user's root directory
          to contain a list of the user's folders and add the INBOX
          folder to the table
 
    - note that the CSL routines called to Enroll and Delete users
      can only be called synchronously.  Bulk enrolls and deletes
      should not be done at a peak time for client use since their
      response will be impacted.
 
    - there is only a single thread processing administrator requests.
      Multiple concurrent requests will be processed synchronously.
 
 
 
7)  MAIL COMING INTO THE IMAP SERVER:
    ---------------------------------
 
    - if the SMTP machine has been configured to route mail to the
      IMAP server then all local mail for the system will be routed
      over to the IMAP server.
 
    - the IMAP server's mail arrival thread will use the *SPL system
      service to read in the note data and, if the mail is destined
      for an enrolled IMAP user, it will add the message to the user's
      INBOX by doing the following:
 
       -- generating a UID (unique identifier) message attribute for
          the message
       -- parsing the note and writing the data into a file in the
          user's INBOX directory using the UID for a filename and
          a filetype of NOTE (if the note was a multipart note an
          index of the parts will also be created also using the UID
          for a filename and a filetype of PARTINDX)
       -- adding an entry to INBOX's NOTE INDEX file for the new
          message
       -- updating the entry for INBOX in MAILBOX INDEX to have
          updated counts of total messages, unseen messages, etc.
 
    - if the note is for a user that is not a registered IMAP user
      the file is transferred to their virtual reader.
 
 
 
8)  CLIENT INTERACTION WITH THE IMAP SERVER:
    ----------------------------------------
 
     - while the IMAP server is up and running, users can use any
       client that supports the IMAP4rev1 protocol (RFC2060) to
       connect to the IMAP server and perform IMAP client functions
       (such as creating/deleting/renaming mailboxes, checking for
       new messages, deleting messages, etc.)
 
     - in order for the client to get into the authenticated state,
       it is necessary to send a LOGIN command (rather than the
       AUTHENTICATE command).  The initial release of the server
       requires that the userid and password be a valid VM
       userid/password pair and the userid must be enrolled in
       the IMAP mailstore (LOGIN processing checks that the user
       has an INBOX directory in the filepool)
 
     - The IMAP server supports all of the IMAP commands documented
       in RFC 2060 with the following exceptions:
 
        -- optional AUTHENTICATE command is not supported (the LOGIN
           command must be used to get to the authenticated state)
           (we hope to provide an AUTHENTICATE exit in the future
           that would allow a site to use what ever form of
           authentication they wish).
 
        -- there are no experimental commands supported
 
 
 
9)  SERVER SIZING RECOMMENDATIONS
    -----------------------------
    - we recommend that the IMAP server initially be given a storage
      size between 128M and 256M.  If you're expecting heavy usage
      (>3000 concurrent users) you should increase this amount.
      Beta level 1.6 requires significantly less storage to support
      a given workload than earlier levels did (the threading logic
      has been redesigned, each client connection no longer requires
      a dedicated thread).