OPS-6.old, DAT=92.03.26.

[Alf Hansen <[e-mail]>]

------------------------------ Start of body part 1

My appologies if this is the wrong version. I trust that the authors will
correct my eventual mistake. 

Best regards,
Alf H.

------------------------------ Start of body part 2

#H DOC=procedures/operate-rfc1148-gwy; RES=COSINE-MHS Project Team; DAT=92.03.26
#     [e-mail]
#     C=CH; ADMD=arCom;PRMD=SWITCH;O=SWITCH;OU=COSINE-MHS;S=Project-Team


        Procedures for Maintaining RFC-1148bis Gateway Mapping Tables
        -------------------------------------------------------------
        Original: 'operate-rfc987-gwy' written by:
        Haavard Kvernelv, RARE MHS Project


        Renamed and Rewritten as: 'operate-rfc1148-gwy' by
        Jeroen Houttuin, Paul Klarenberg, Jim Romaguera, COSINE MHS project 
        team.
        (rewrite for RFC-1148bis and updated operational procedures, 92.02.06)




Scope
-----
This document defines the procedures to be followed by the MHS managers
during the regularly scheduled updates of the RFC-1148bis gateway
mapping tables. The goal is the optimum flow of electronic mail between
users of X.400 MHS and users of RFC-822 e-mail systems. How this can be
achieved technically is defined in RFC-1148bis, see [RFC1148bis]. This
document describes the corresponding procedures, that should be
followed by ALL operators of RFC-1148bis gateways to give optimum
results. These procedures make extensive reference via examples of how
to use automated tools to achieve the results from each step. It is not
necessary to use a tool to perform each step but it is considered
HIGHLY desirable. If a gateway which is in use in the COSINE MHS
community is not covered in steps (15) and (16), the COSINE MHS Project
Team should be informed. The relevant software specific instructions,
if sent to the COSINE MHS Project Team:

          [e-mail] or
          C=CH;ADMD=arCom;PRMD=SWITCH;O=SWITCH;OU=COSINE-MHS;S=Project-Team

will be added to these procedures.


Participants
------------
The parties involved in this procedure are:


(1)     The MHS managers
(2)     The COSINE MHS project team




Procedures
----------


[Proc-1] describes how mapping tables 1 and 2 are to be created.
[Proc-2] contains the table update schedule. To assure coordinated 
installation of the international mapping tables in every gateway in 
the world as is required by RFC-1148bis, see [RFC1148bis], the following 
procedure defines the exact steps to be followed by the MHS manager in 
conjunction with the COSINE MHS project team . The command line examples 
given in steps (0) to (16) apply to SUNOS.


Of the following procedural steps, step (0) is to be followed if the
MHS manager has not yet installed the RFC-1148bis mapping and gateway 
tables validation tool ie. 'chk1148', or whenever a new version of the 
'chk1148' tool is released. Steps (1) to (4) have to be followed every time 
the MHS manager submits new mapping and gateway tables. Steps (5) to (10) 
have to be followed by the COSINE MHS Project Team whenever the new 
international mapping and gateway tables are generated. Steps (11) to (16) 
have to followed every time the MHS manager distributes new mapping and gateway
tables. A summary is given in Table 1.



     event:                          steps to be followed:  by whom:
     ------------------------------------------------------------------
     new release 'chk1148'           0                      MHS manager
                                                            
     submitting new mapping
     and gateway tables              1, 2, 3, 4             MHS manager


     generating new international
     mapping and gateway tables      1, 5, 6, 7, 8, 9, 10   Project Team
                                                            
     distributing new mapping 
     and gateway tables              1, 11, 12, 13, 14, 15, MHS manager
                                     16                      


     ------------------------------------------------------------------


                        Table 1.




STEPS TO BE DONE BY THE MHS MANAGER TO USE VALIDATION TOOL
----------------------------------------------------------


Step (0) needs to be followed.


0. Retrieve and install the validation tool, 'chk1148'. 


     The software package is distributed in one single shell archive file,
     in both compressed and uncompressed forms. These files can be
     retrieved from the COSINE MHS information server by e-mail or by FTP.
     First make a special directory for the tool, e.g. /usr/lib/chk1148
     with the proper write privileges set. Then type the following:


          %cd /usr/lib
          %mkdir chk1148
          %cd chk1148


     Retrieve the distribution package in one of the following ways:


     by e-mail:
       Send a message to:
            [e-mail] or
            C=CH;ADMD=ARCOM;PRMD=SWITCH;O=switch;OU=nic;S=cosine-mhs-server
       with the following line in the body-part:
            send tools/operational/chk1148-SUNOS/chk1148.shar

       You will receive a message containing the distribution package.

       NOTE: The compressed version cannot be retrieved per e-mail.

     by anonymous FTP:
          %ftp nic.switch.ch
          Name (nic.switch.ch:user): cosine-mhs
          Password:<your E-mail address in RFC822 format (user@domain)>
          ftp>cd /e-mail/COSINE-MHS/tools/operational/chk1148-SUNOS
       continue for the uncompressed version with:
          ftp>get chk1148.shar
          ftp>quit
       or otherwise for the compressed version with:
          ftp>binary
          200 Type set to I.
          ftp>get chk1148.shar.Z
          ftp>quit


     If you retrieved the compressed version, uncompress it first:

          %uncompress chk1148.shar.Z

     Now, unpack the shell archive:

          %sh chk1148.shar

     Read the installation guide carefully before installing and using the
     software. For details on how to use the tool please refer to the
     command reference which is also part of the distribution package.


STEPS TO BE DONE BY THE MHS MANAGER TO SUBMIT NEW TABLES 
---------------------------------------------------------


Steps (1) to (4) need to be followed.

NOTE: in this version of chk1148, the DNS checking option is not very
      stable. As a result of this, these operational procedures
      always use the '-c n' option to disable DNS checking.
      Instead of DNS, the data file 'rfc822.chk' is used. This will 
      produce warnings for 'new' Internet (sub)domains, even if such 
      domains are already registered. Please do check if the domains 
      that produce such warnings have indeed been registered.

1. Retrieve up-to-date data files before running the 'chk1148' tool.


     For the tool to function reliably, it needs the following 4 up-to-date
     datafiles, which are generated by the Project Team every time a request 
     for mapping table updates is sent out:

          iso3166.chk
          admd.chk
          rfc822.chk
          x400.chk

     The MHS manager checks the last modification date of his datafiles 
     and the datafiles in the server to confirm that he has the latest version; 
     if not he retrieves the datafiles. He may, if he wishes, retrieve the 
     datafiles every time he is doing this procedure. The datafiles can be 
     retrieved in the same way as the chk1148 tool is (i.e. step (0)), but from 
     another directory:


          mapping-tables/chk1148-data-files


2. Create mappings.


     The national gateway manager prepares the address mappings and gateway
     table in RFC1148bis syntax in the following files:


     xy.map1:       country xy's X.400 to RFC822 mappings
     xy.map2:       country xy's international RFC822 to X.400 mappings
     xy.map2.local: country xy's national (local) RFC822 to X.400 mappings
     xy.gate:       country xy's contribution to international gateway
                    table
     xy.gate.local: country xy's national part of the gateway table.



3. Validate the tables.


     Before submitting xy.map1, xy.map2 and xy.gate, the MHS manager 
     should make sure all tables are error free as defined by RFC-1148bis, 
     see [RFC1148bis]. To automatically validate the tables, firstly apply
     the validation tool to xy.map1 and the  concatenation of xy.map2 and 
     xy.map2.local, secondly apply the 'chk1148' tool to syntactically check 
     the concatenation of xy.gate and xy.gate.local. For example firstly:


          %cat xy.map2 xy.map2.local > xy.map2.complete
          %chk1148 -c n xy.map1 xy.map2.complete > chkreport


      and then secondly:


          %cat xy.gate xy.gate.local > xy.gate.complete
          %chk1148 -m r -c nru xy.gate.complete


     If the 'chk1148' tool detects any errors, correct them and then
     rerun the validation tests no errors remain.


     There are two points to take note of when running 'chk1148'. They
     are listed below as NOTE 1 and NOTE 2. These points apply to steps
     (3), (4) and (7).


     NOTE 1:
         For RFC822 domain checking the tool uses the RFC822 domain
         data file 'rfc822.chk' and the Domain Name Server (DNS) by
         default. If the DNS is not available on the system the DNS
         checking function should be disabled using the option -c n.
         It is however advantageous to actually use the DNS, since it
         gives more up-to-date information on RFC822 domains than the
         RFC822 domain data file.


     NOTE 2:
         By default the tool checks whether an X.400 domain is
         declared as routable via a COSINE MHS WEP. Passing this
         check is not mandatory for mapping rules, and generally
         generates a lot of warnings. The function can be disabled
         by using the option -c x.

     NOTE 3:
          There is one syntax rule that chk1148 does not check: maximum
          lengths of attribute values as described in Annex B of X.411. 
          When defing mapping tables, do not exceed the following 
          maximum lentghs:

               ADMD    16
               PRMD    16
               O       64
               OU      32
               S       40
               G       16

4. Submit tables to COSINE MHS project team.


     Send three messages containing xy.map1, xy.map2 and xy.gate by E-mail to:
          [e-mail] or
          C=CH;ADMD=arCom;PRMD=SWITCH;O=SWITCH;OU=COSINE-MHS;S=Project-Team




STEPS TO BE DONE BY THE COSINE MHS PROJECT TEAM TO GENERATE NEW TABLES
----------------------------------------------------------------------


The steps (5) to (10) are ONLY followed by the project team. These
steps are included in this operational procedure to explicitly
show what checks have been performed by the Project Team. The MHS manager
may continue reading at step (11) if he wishes.


5. Verify national tables.


     The project team checks the national tables that were submitted by
     a country xy to ensure they are conformant to RFC1148bis. This is
     done by applying 'chk1148' in the following way:


          %chk1148 -m x -c n xy.map1 > chkreport1
          %chk1148 -m r -c n xy.map2 > chkreport2
          %chk1148 -m r -c n xy.gate > chkreport3


     If any of the tables contains ANY ERROR, all tables for country
     xy will be refused.


6. Concatenate national tables.


     The project team creates the international mapping tables by
     concatenating all the new error free national tables with all the
     previous unchanged national tables. The international mapping
     tables are stored in the files:


          - rfc1148-mapping1:  concatenation of all xy.map1 tables
          - rfc1148-mapping2:  concatenation of all xy.map2 tables
          - rfc1148-gate    :  concatenation of all xy.gate tables


7. Validate international mapping tables.


     The project team verifies these concatenated tables are conformant
     to RFC-1148bis, see [RFC1148bis] except no checks for symmetry or 
     inverse mapping rules are performed. This is due to no local mappings 
     being available for such tests. The 'chk1148' tool is applied as
     in the following example:


          %chk1148 -c nsS rfc1148-mapping1 rfc1148-mapping2 > chkreport1


8. Validate international gateway table.


     The project team tests the gateway table is conformant to ref
     [RFC1148bis]. Nonunique left hand sides are allowed in the RFC1148
     gateway table.  The 'chk1148' tool is applied as in the next
     example:


          %chk1148 -m r -c nu rfc1148-gate > chkreport2



9. Ensure international tables are error free.


     The project team analyses the errors and warnings resulting from steps
     (5) to (8). Only syntactically correct (i.e. no errors after steps (5) 
     to (8)) international mapping tables will be distributed to the 
     MHS managers.


10. Announce that international tables are ready to be retrieved.


     The COSINE MHS project has concatenated the national mappings and
     checked the resulting international mapping tables,
     rfc1148-mapping1, rfc1148-mapping2, and rfc1148-gate, as specified
     in step (5) to (9). An e-mail is sent out on the rd-mhs-managers list:

          C=CH;ADMD=ARCOM;PRMD=SWITCH;O=switch;OU=cosine-mhs;S=rd-mhs-managers
          ([e-mail])

     announcing that the tables are available. The tables are immediately 
     afterwards also distributed via e-mail on this same list.




STEPS TO BE DONE BY THE MHS MANAGER TO DISTRIBUTE NEW TABLES
------------------------------------------------------------


Steps (11) to (16) need to be followed.


11. Retrieve international tables


     Retrieve the tables from COSINE MHS file server, in one
     of two ways:


    -per mail:


     Send three mails to:
          [e-mail] or
          C=CH;ADMD=ARCOM;PRMD=SWITCH;O=switch;OU=nic;S=cosine-mhs-server;
     one with the following line in the body-part,
          send mapping-tables/rfc1148-mapping1
     one with a line
          send mapping-tables/rfc1148-mapping2
     and one with a line
          send mapping-tables/rfc1148-gate


     You will receive three messages containing the new tables.


    -per anonymous ftp:


          %ftp nic.switch.ch
          Name (nic.switch.ch:user): cosine-mhs
          Password: <your e-mail address in RFC822 format (user@domain)>
          ftp>cd mapping-tables
          ftp>get rfc1148-mapping1
          ftp>get rfc1148-mapping2
          ftp>get rfc1148-gate
          ftp>quit



12. Customize tables.


     Make the tables complete by adding the national (local) parts to 
     rfc1148-mapping2 and rfc1148-gate. For example:


          %cat xy.map2.local >> rfc1148-mapping2
          %cat xy.gate.local >> rfc1148-gate


13. Validate the customized tables


     Conflicting mappings can exist between the local mappings of
     country xy and the international mappings of other countries. Any
     such conflicts must be resolved. For example, run the 'chk1148' tool 
     such that on the MHS managers country's customized tables, only the 
     warnings that apply to his country are displayed.
     The warnings related to other countries can be suppressed by
     applying a filter to the output of the tool.  The following two
     examples respectively show how to run the tool without and with such a
     filter. (The second example is for the country Switzerland, i.e.
     country code of 'CH'.)


     example 1:
          %chk1148 -c n rfc1148-mapping1 rfc1148-mapping2 > chkreport


     example 2:
          %chk1148 -c n rfc1148-mapping1 rfc1148-mapping2\
          | grep '^CH' > chkreport


     If there are errors, fix them!


14. Prepare tables for all supported MTAs.


     The tables in RFC-1148bis syntax must, for most MTAs, be
     translated into an MTA specific format. There are tools available
     to perform this task for the main public domain gateways. The next
     sections describe the changes, if any, required for each of the
     most widely used gateways plus the available MTA translation tools.


14.1. DFN-EAN


     DFN-EAN uses two files in 'readable format', called rfc987.x and
     rfc987.r. The tool make987.c, which can be retrieved from the
     [tools/operational/dfn-ean] directory of the COSINE MHS information
     server, is normally used for creating  these files. It should be
     retrieved using the methods described in step (0). It should then be
     compiled using cc:


          %cc -o make987 make987.c


     To create the files, use the following command lines:


          %make987 readx rfc1148-mapping1 rfc987.x
          %make987 readr rfc1148-mapping2 rfc987.r


14.2. EST-EAN


     EST EAN uses the same format as DFN-EAN, except that the "strong
     syntax" is not supported. AWK scripts that convert from standard
     mapping tables to EST EAN mapping tables are part of the "eancare"
     package. This package can be  retrieved from the COSINE MHS server in
     directory [tools/operational/est-ean]. The tool is archived in 
     eancare.shar. It should be extracted by feeding it to a shell:


          %sh eancare.shar


     This will create a new directory called r987 where the awk scripts
     map1-to-ubc.awk and map2-to-ubc.awk can then be found.


     The following commands demonstrate how to use these scripts to convert
     the customized tables into EST EAN format:


          %awk -f map1-to-ubc.awk rfc1148-mapping1 > xr.tbl
          %awk -f map2-to-ubc.awk rfc1148-mapping2 > rx.tbl
          %awk -f map2-to-ubc.awk rfc1148-gate > rx-gateway.tbl


14.3. PP


     PP uses the original format, except that in every mapping rule, the
     first '#' sign should be replaced by a ':', and the second one should
     be deleted.
     The following awk programs convert the customized tables into PP
     format tables:


          %awk 'BEGIN { FS = "#"; }{ if ($0 ~ /^#/) print $0; else print\
          $1 ":" $2; }' rfc1148-mapping1 > or2rfc
          %awk 'BEGIN { FS = "#"; }{ if ($0 ~ /^#/) print $0; else print\
          $1 ":" $2; }' rfc1148-mapping2 > rfc2or
          %awk 'BEGIN { FS = "#"; }{ if ($0 ~ /^#/) print $0; else print\
          $1 ":" $2; }' rfc1148-gate > rfc1148gate


14.4. Mailway


     No change needed. Uses rfc1148bis format directly.


15. Announce table update within national network.


     All gateway managers in the national network should be informed that
     the new tables are available, and should be told how to retrieve them.
     The time when the tables are to go into operation must be
     announced by the MHS manager. The installation date for tables is
     as per [PROC-2].


16. Install tables in the national network.


     MTA specific tables must be installed on all gateways in the national
     network. The gateway table rfc1148-gate can be customized per MTA, 
     depending on the MTA manager's preferences about which gateway to use 
     for which domain. Left-hand sides in rfc1148-gate must be unique. 
     chk1148 can be used to verify this uniqueness:

     %chk1148 -m r -c acdinrsSx rfc1148-gate

     The following sections describe the specific files which should be
     installed for different software packages.


16.1. DFN-EAN


     Install rfc987.x and rfc987.r in /usr/spool/ean/sys/mta or, if using
     VMS, in eanroot:[sys.mta]. DFN-EAN has no gateway table.


16.2. EST-EAN


     The files are called xr.tbl , rx.tbl and rx-gateway.tbl and reside 
     in the same directories used for DFN-EAN.


16.3. PP


     Copy the following files to ~pp/tables.
     map1 rules are stored in file '~pp/tablesor2rfc'
     map2 rules are stored in file '~pp/tablesrfc2or'
     gateway rules are stored in file '~pp/tablesrfc1148gate'


     Run dbmbuild


16.4. Mailway


     A shell script 'm.plus.gm', which can be used to install the
     new tables, can be found on the COSINE MHS server in the
     [tools/operational/mailway] directory


References
----------


[PROC-1]     A Tutorial on How to Prepare RFC-1148bis Address Mapping
             Tables, [procedures/table-creation-tutorial].
[PROC-2]     RFC-1148bis Mapping Table Update Schedule
             [procedures/maptable-schedule].
[RFC1148bis] Mapping between X.400(88)/ISO10021 and RFC822,
             Hardcastle-Kille, May 1991.


------------------------------ End of body part 2