IBM/EARN Gateway - User's Guide Version 2.0, January 28th 1992 Dominique Pinse (IBM) and Peter Sylvester (EARN) ii IBM/EARN Gateway - User's Guide You are sad,' the Knight said in an anxious tone: let me sing you a song to comfort you.' Is it very long ? Alice asked, for she had heard a good deal of poetry that day. It's long, said the Knight, but very, VERY beautiful. Everybody that hears me sing it -- either it brings the TEARS into their eyes, or else -- Or else what ?' said Alice, for the Knight had made a sudden pause. Or else it doesn't, you know. The name of the song is called "HADDOCKS' EYES."' Oh, that's the name of the song, is it?' Alice said, trying to feel interested. No, you don't understand,' the Knight said, looking a little vexed. That's what the name is CALLED. The name really IS "THE AGED AGED MAN."' Then I ought to have said "That's what the SONG is called" ?' Alice corrected herself. No, you oughtn't: that's quite another thing. The SONG is called "WAYS AND MEANS": but that's only what it's CALLED, you know.' Well, what IS the song, then ?' said Alice, who was by this time completely bewildered. I was coming to that,' the Knight said. The song really IS "A-SITTING ON A GATE": and the tune's my own invention.' Through the looking glass by Lewis Carroll iii iv IBM/EARN Gateway - User's Guide TABLE OF CONTENTS Notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 How to read this guide ? . . . . . . . . . . . . . . . . . . . . 1 Before using the gateway . . . . . . . . . . . . . . . . . . . 1 If you are in IBM . . . . . . . . . . . . . . . . . . . . . . . 1 If you are an EARN or Internet user . . . . . . . . . . . . . . 2 Some more hints . . . . . . . . . . . . . . . . . . . . . . . . 2 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 Overview of the gateway . . . . . . . . . . . . . . . . . . . . . 2 Code of conduct . . . . . . . . . . . . . . . . . . . . . . . . . 4 Registration process for IBMers . . . . . . . . . . . . . . . . . 4 How to get an IEA . . . . . . . . . . . . . . . . . . . . . . . 5 First method . . . . . . . . . . . . . . . . . . . . . . . . . 5 Second method . . . . . . . . . . . . . . . . . . . . . . . . . 5 Creation of the EARN address of the IBMer . . . . . . . . . . . 6 Registration process for EARN users . . . . . . . . . . . . . . . 8 Automatic registration of an EARN user . . . . . . . . . . . . 8 Registration of an EARN user by an IBMer . . . . . . . . . . . 8 Sending notes from IBM to EARN . . . . . . . . . . . . . . . . . 10 Sending notes from EARN to IBM . . . . . . . . . . . . . . . . . 11 Receiving notes from EARN to IBM . . . . . . . . . . . . . . . . 11 Receiving notes from IBM to EARN . . . . . . . . . . . . . . . . 12 Viewing directory entries from EARN . . . . . . . . . . . . . . . 12 Viewing an IBMer . . . . . . . . . . . . . . . . . . . . . . . 12 Viewing one's own X.400 attributes . . . . . . . . . . . . . . 13 Viewing directory entries from IBM . . . . . . . . . . . . . . . 13 Viewing one's entry . . . . . . . . . . . . . . . . . . . . . . 13 Addressing scheme . . . . . . . . . . . . . . . . . . . . . . . . 14 IBM/PROFS addresses . . . . . . . . . . . . . . . . . . . . . . 14 X.400 addresses . . . . . . . . . . . . . . . . . . . . . . . . 14 EARN addresses . . . . . . . . . . . . . . . . . . . . . . . . 16 Address conversion . . . . . . . . . . . . . . . . . . . . . . . 16 Between IBM/PROFS and X.400 . . . . . . . . . . . . . . . . . . 16 Between EARN and X.400 . . . . . . . . . . . . . . . . . . . . 16 Conversion of EBCDIC characters . . . . . . . . . . . . . . . . . 17 Table of Contents v vi IBM/EARN Gateway - User's Guide NOTICE The status of the gateway described here is experimental. Some infor- mation given in this document is subject to change because it is an experimental gateway. The configuration of the gateway and the func- tions of the software used may change during the pilot phase. In addition, the IBM Mail Exchange facility will be improved and the current service will be enhanced. In order to help us open the pilot service very soon, CIRCE (host of the gateway) allows us to use their name space (circe.fr) to address IBMers in the Internet. These addresses are temporary and by end of the pilot phase, we hope to be able to chose a final format. Users will be warned of the change. HOW TO READ THIS GUIDE ? This guide explains to you, dear IBM or EARN user, how to use the IBM Mail/EARN gateway. BEFORE USING THE GATEWAY If you want to use this gateway, please start reading with the fol- lowing introduction chapters: * "Overview of the gateway" on page 2 * "Code of conduct" on page 4 IF YOU ARE IN IBM You read the chapters: * "Registration process for IBMers" on page 4 * "Sending notes from IBM to EARN" on page 10 * "Registration of an EARN user by an IBMer" on page 8 * "Receiving notes from EARN to IBM" on page 11 * "Viewing directory entries from IBM" on page 13 1 IF YOU ARE AN EARN OR INTERNET USER You read the chapters: * "Registration process for EARN users" on page 8 * "Sending notes from EARN to IBM" on page 11 * "Receiving notes from IBM to EARN" on page 12 * "Viewing directory entries from EARN" on page 12. SOME MORE HINTS If you want to have more technical information on the addressing schemes used in this gateway, read the following chapters: * "Addressing scheme" on page 14 * "Address conversion" on page 16 * "Conversion of EBCDIC characters" on page 17 CONTACT To get help, you can contact Dominique Pinse. IBM e-mail address: PINSE at PARIS EARN e-mail address: PINSE at FRIBM11 or PINSE@FRIBM11.BITNET OVERVIEW OF THE GATEWAY A new electronic mail gateway between the EARN and the IBM internal PROFS networks is now available for pilot use. It allows communi- cation (i.e. electronic mail exchange) between IBMers and their corre- spondents in the academic community whether they are on EARN, BITNET or INTERNET. EARN, the European Academic and Research Network was launched by IBM in 1983. Today, it is made up of about 600 universities and research institutions throughout Europe, the Middle East and Africa. EARN shares common technology and protocol with its peer networks in the USA (BITNET) and Canada (NetNorth). Most of the academic networks in the world may be accessed through EARN, including the Internet or EUnet and some national networks like JANET in the UK, DFN in Germany or Nordunet in Nordic countries. This gateway is open to all of these networks. To facilitate the reading of this document the word EARN will be a synonym for EARN/BITNET/Internet. 2 IBM/EARN Gateway - User's Guide The international mail system within IBM is based on PROFS and all IBMers have access to it and can communicate with their IBM col- leagues. On the IBM side Each IBMer may normally use his PROFS system and no special user interface is required because EARN addresses are translated into IBM/PROFS addresses. On the EARN side The usual mail user interfaces can be used because IBM/PROFS addresses are translated into Internet like addresses. This gateway uses the X.400 standard as an intermediate protocol between the IBM/PROFS mail system and the EARN RFC-822 mail. X.400 is the name of a series of recommendations produced by CCITT (Consultative Committee on International Telephony and Telegraphy) for electronic mail which is used to interconnect several electronic mail services. This means that the gateway is comprises two gateways, one between IBM and X.400, the other one between X.400 and EARN. But, this is highly transparent to end users, no special user agent is required to use the gateway and communicate from IBM to EARN and vice-versa. In IBM, the IBM Mail Exchange service provides a gateway between its internal PROFS mail system and X.400. On EARN, the Queens software acts as a gateway between the EARN mail and X.400. * IBM Mail Exchange is a worldwide store and forward electronic mail distribution service of IBM Information Network. It allows the exchange of electronic mail between IBM/PROFS and the outside world providing also a user directory for all IBM and non IBM users. Therefore, in order to be able to use the gateway, all IBMers and EARN users must be registered in this directory. * The Queen's University at Kingston Message Handling System soft- ware has been written by Andy Hooper and improved by GMD in Bonn where it is used as a gateway between DFN and EARN. The Queens software runs on VM and is installed on the CIRCE (CNRS) machine in Orsay (France), which is also an EARN node. It converts X.400 mail received from IBM and sends it to EARN, and vice-versa. No registration of users is necessary in this part of the gateway because algorithmic conversions are automatically performed by the Queens software. * The physical connection between the two X.400 systems is based on an X.25 leased line between CIRCE (Orsay) and IBM (Marne-la- Vallee). This gateway allows the exchange of text called IA5Text in X.400 ter- minology. The EBCDIC character set is used both within IBM and on EARN, and these characters are translated into IA5Text by the gateway. Thus, it is not possible to transfer binary files through the gateway. Moreover, some special characters (i.e the dollar sign) cannot be be exchanged in a transparent mode. Please, read chapter "Conversion of 3 EBCDIC characters" on page 17 for the description of these transf- ormations (Note: sorry this chapter is not yet done). CODE OF CONDUCT Generally speaking, each network defines its proper rules and guide- lines. With a gateway between two networks, the implicit and explicit rules of the two networks should be respected. EARN has established its Code of Conduct which is a document (called "EARN Code Of Conduct.") reminding users of the intended purpose of EARN which is to facilitate the exchange of information consistent with the academic, educational and research purposes of its members. This network shouldn't be relied upon for transmission of confidential or sensitive data because EARN cannot guarantee its security. More- over, the use of the network for political and religious activism is forbidden and it is obvious that courtesy is recommended. On the other side, the users of the gateway must be in accordance with the "IBM Business Conduct Guidelines." The gateway is to be used to facilitate communication between IBMers and their colleagues in the academic world in mutual research and joint studies. The gateway must never be used for business promotion, such as unsolicited product announcements, information which is IBM internal use or of higher sen- sitivity, and proprietary information. REGISTRATION PROCESS FOR IBMERS In the EARN community, the electronic mail address of an IBMer cannot be his normal PROFS address, for example: F055010 at MLVVM5 or MLVVM5(F055010) He needs to get an Internet like alias of this PROFS address, which format should look like: user@list.of.domain.names The IBM Mail Exchange system provides a user directory in which all users on the IBM side of the gateway should register in order to be known and obtain an X.400 address. Below, you'll find the process required to get your X.400 address and create your EARN address. 4 IBM/EARN Gateway - User's Guide HOW TO GET AN IEA Today, to communicate with a partner outside IBM, all IBMers must have an Inter-Entreprise Address or IEA. This address will not be used to communicate with EARN but an IBMer who needs to communicate with a partner outside IBM must obtain it. For example, the IEA of Dominique Pinse in IBM France is: FRIBM9GM at IBMMAIL receive a note from IBM Mail Exchange advising you that you need one. To get your IEA, just type the MXMENU command as described in the fol- lowing chapter. If this command is not available, send a simple note (with any content) to the address: REGISTER at IBMMAIL or IBMMAIL(REGSITER) Then, IBM Mail Exchange allocates an IEA for you and informs you when it is done. Today, the above methods are not possible in the UK where you have to ask user administration to obtain your IEA. Thus send a note to: 3UANOSS at UKSSVM1 FIRST METHOD This method is recommended because it is the simplest and it allows you to obtain both your X.400 (EARN) address and your IEA. When you are on your PROFS office system, just type the command: MXMENU Then, to get registered, chose the following function: Add your address information in Mail Exchange user directory. SECOND METHOD This manual method may always be used if MXMENU is not available on your system. Just send a note with your usual office system to the following address: 5 DIRECT at IBMMAIL or IBMMAIL(DIRECT) and write the following lines as the text lines of the note: directory=add userid=PROFS userid at=PROFS node surname=name initials=initials of the given names alias=given name company=IBM access=0 Example: directory=add userid=F055010 at=MLVVM5 surname=Pinse initials=D alias=Dominique company=IBM France access=0 CREATION OF THE EARN ADDRESS OF THE IBMER Once you have performed the registration (with one of the previous methods) the user directory sends you back a file named: DIRECT REPLY In this file, you'll find the result of your registration and your X.400 attributes. You'll use them to create your EARN address. In this file, you can find, among other, the following lines: Given name : , Surname : and Country code: . The X.400 standard specifies that the Given name attribute is the real given name of the user but in IBM Mail Exchange the given name becomes the surname followed by the initials of the given names. For example, Dominique Pinse (IBM in France), has the following attri- butes: Country code : FR ADMD name : IBMX400 PRMD name : IBMMAIL Surname : PINSE Given name : PINSED Peter Streibelt (IBM in Germany) has: 6 IBM/EARN Gateway - User's Guide Country code : DE ADMD name : IBMX400 PRMD name : IBMMAIL Surname : STREIBELT Given name : STREIBP And Francesco Greco (IBM in Italy) has: Country code : IT ADMD name : IBMX400 PRMD name : IBMMAIL Surname : GRECO Given name : GRECOF The attribute ADMD name is always IBMX400 and the attribute PRMD name is always IBMMAIL. The attribute Country code is automatically created and managed by IBM Mail Exchange, it is the entry point of the service IBM Mail in the country. The EARN address of the IBMer is then composed of these attributes separated by dots and is written: givenname.surname@ibmx400-country.ibmmail.circe.fr The @ sign is mandatory and means "at". Upper and lower cases are not significant and blank characters are not allowed in the address. Note that the string ibmmail.circe.fr at the end of the address represents the gateway. For example, the EARN address of Dominique Pinse of IBM in France is: pinsed.pinse@ibmx400-fr.ibmmail.circe.fr The address of Peter Streibelt of IBM in Germany is: streibp.streibelt@ibmx400-de.ibmmail.circe.fr And the address of Francesco Greco of IBM in Italy is: grecof.greco@ibmx400-it.ibmmail.circe.fr Note: The characters ibmx400- are completely redundant and are only used to avoid having a country code adjacent to the @ sign which can be confusing for users in the UK. You can now communicate this electronic address to all your corre- spondents on EARN, BITNET, Internet or any other network because it is known everywhere. 7 REGISTRATION PROCESS FOR EARN USERS An EARN user cannot be reached from IBM with is real address, which is for example: Francois.Mitterrand@Elysee.fr He needs to register in the IBM Mail Exchange user directory in order to get a PROFS alias (userid at profid) that any IBMer can reach from his usual office system. The registration process for an EARN user is explained below: AUTOMATIC REGISTRATION OF AN EARN USER In some cases, the registration of EARN users is done automatically by the system. IBMers can give their IBM/EARN addresses (created as explained above in the chapter "Registration process for IBMers" on page 4) to their partners on EARN by telephone call, meeting, business card, normal mail or fax. For example, Dominique Pinse of IBM will give her address: pinsed.pinse@ibmx400-fr.ibmmail.circe.fr In this case, it should be easy to send a mail to this address from EARN using an Internet mail user interface. It is recognized every- where. When the mail crosses the gateway, IBM Mail Exchange adds a new entry in the user directory for the originator of the mail and creates a PROFS address which looks like: 12345678 at IBMMAIL This registration is done once. REGISTRATION OF AN EARN USER BY AN IBMER If an IBMer wants to initiate the communication with his EARN col- league, he may use the following steps. 1. Obtain the address of the EARN partner by telephone call, meeting, normal mail or fax. 2. If it is a pure EARN/NJE or a pseudo Internet address, i.e.: userid at nodeid or userid@nodeid.bitnet 8 IBM/EARN Gateway - User's Guide Get the userid (left part of the address), and send a note with your office system to: DIRECT at IBMMAIL or IBMMAIL(DIRECT) with the following line: directory=xadd x400= prmd=earn admd=ibmx400 country=fr surname=userid orgname=nodeid 3. If it is a pure Internet address, i.e.: userid@list.of.domain.names Send a PROFS note to: DIRECT at IBMMAIL or IBMMAIL(DIRECT) with the following lines: directory=xadd x400= prmd=earn admd=ibmx400 country=fr domain1t=RFC-822 domain1v1=userid(a)list.of.domain.names Be aware that Internet addresses, i.e. userid@list.of.domain.names, have some special characters. These characters are not accepted by X.400 and must be converted in the following manner: @ becomes (a) % becomes (p) | becomes (b) " becomes (q) _ becomes (u) And don't forget to always convert the @ sign into (a) as his it shown in the above example. 4. IBM Mail Exchange adds this new entry in the user directory and creates a PROFS alias: 9 12345678 at IBMMAIL or IBMMAIL(12345678) This alias is sent back to the user in a file named: DIRECT REPLY 5. With the same method, you can register several EARN users in a single directory=xadd request. Just add a line with "x400=" as a separator between the different entries, as shown in the above example: directory=xadd x400= prmd=earn admd=ibmx400 country=fr orgname=dbngmd21 surname=grz027 x400= prmd=earn admd=ibmx400 country=fr domain1t=RFC-822 domain1v1=Francois.Mitterrand(a)Elysee.fr 6. Be aware that the attributes admd=ibmx400, prmd=earn, country=fr and domain1t=RFC-822 must be written as shown in the example and must not be changed because they are specific of this gateway. SENDING NOTES FROM IBM TO EARN Now, for IBMers, EARN users have normal PROFS addresses. In order to send a note to a colleague on EARN, just send a normal PROFS note to his alias as you would do with any IBMer. This means that you can send a same note whose recipients are both IBMers and EARN users. If you find that the numeric aliases are not nice, just create personal PROFS alias for them. You can also build mixed distribution lists. Example: header of a note from Dominique (IBM) to Peter (EARN). De: MLVVM5(F055010) A: IBMMAIL(4949) Dominique's IBM/PROFS address is: F055010 at MLVVM5 Peter's PROFS alias is: 4949 at IBMMAIL 10 IBM/EARN Gateway - User's Guide SENDING NOTES FROM EARN TO IBM Now, for EARN users, IBMers have Internet (RFC-822) addresses. Internet (RFC-822). Be aware that these are not pure NJE addresses and that the user interfaces for Internet mail should be used: the Mail command for VM/CMS or the UCLA/Mail software for MVS. You'll find all the commands available in the major operating systems in the EARN Pocket Guide. Thus, all usual Internet mail facilities can be used to communicate with your IBM partners. Example: header of a mail from Peter (EARN) to Dominique (IBM): From: Peter Sylvester To: Dominique Pinse Peter's EARN/NJE address is: GRZ027 at DBNGMD21 and in a pseudo-Internet format: grz027@dbngmd21.bitnet Dominique's EARN/Internet address is: pinsed.pinse@ibmx400-fr.ibmmail.circe.fr RECEIVING NOTES FROM EARN TO IBM For the time being, when a message is sent from EARN to IBM it arrives at IBM as a PROFS documents in stead of a PROFS note. This unexpected behavior of the software has been pointed out to the IBM Mail Exchange architects and developers. We expect an appropriate and rapid enhancement of the software so that IBMers may receive normal PROFS notes and thus be able to use the PROFS facilities for handling messages from EARN. 11 RECEIVING NOTES FROM IBM TO EARN The notes sent by IBMers arrive as Internet messages. Some minor inconvenience still exists today (for example, the PROFS header appears in left as part of the body) but it will be corrected. VIEWING DIRECTORY ENTRIES FROM EARN Any EARN user may view specific entries in the IBM Mail Exchange user directory by sending a mail to: direct.direct@ibmx400-gb.ibmmail.circe.fr VIEWING AN IBMER If you want to find a specific IBMer whose name you know, enter the following lines as text of the note: directory=view surname=the surname of the IBMer detail=y For example, you can view all users in IBM whose last names begin with the letters shakesp: directory=view surname=shakesp* detail=y The system retrieves from the user directory the entry or entries you specified and returns a file with the following information: Country code : FR ADMD name : IBMX400 PRMD name : IBMMAIL Surname : SHAKESPEARE Given name : SHAKESW The EARN address of this person is: shakesw.shakespeare@ibmx400-gb.ibmmail.circe.fr Please read chapter "Creation of the EARN address of the IBMer" on page 6 for the details. 12 IBM/EARN Gateway - User's Guide Note 1: when an EARN user sends a first message to the directory, he is automatically registered. Note 2: it is not possible to retrieve the entry of an IBMer who hasn't registered (the system send a message specifying that no entry has been found). VIEWING ONE'S OWN X.400 ATTRIBUTES An EARN user can view his X.400 attributes by sending a message to the IBM Mail Exchange directory with the single line: directory=change The IBM Mail Exchange directory will then add a new entry for this user and send him back the list of his X.400 attributes. This is an easy way to register in the directory. VIEWING DIRECTORY ENTRIES FROM IBM VIEWING ONE'S ENTRY An IBM/PROFS user can view his own entry in the IBM Mail Exchange directory. Just type: MXMENU and chose the line: View address information in Mail Exchange user directory. If MXMENU is not available, just send a note to: DIRECT at IBMMAIL or IBMMAIL(DIRECT) with the following lines a text of the note: directory=view surname=its own surname detail=y 13 The directory sends back the result in a file: DIRECT REPLY Unfortunately, it is not possible to view an EARN user because his real surname doesn't appear in the directory (there is only his EARN or Internet address). ADDRESSING SCHEME As explained above, the EARN/IBM gateway is made of two gateways: one between IBM/PROFS and X.400, the other one between X.400 and EARN. Therefore, three different formats of addresses are necessary (IBM/PROFS, X.400 and EARN) for each EARN or IBM user. These addresses and the conversion rules are explained below. IBM/PROFS ADDRESSES They are used within the IBM internal office system PROFS. userid at profsid or profsid(userid) Example: F055010 at MLVVM5 or MLVVM5(F055010) X.400 ADDRESSES These addresses are used only by the gateway. They are not official X.400 addresses known by X.400 administrations like France Telecom, Deutsche Bundespost or Sprint. They are made of different attributes like the country code, the administration management domain or the surname of the person. As IBM Mail Exchange is the administrator of this X.400 service all IBM/PROFS and EARN addresses have an attribute administration manage- ment domain (admd) set to: admd=IBMX400 14 IBM/EARN Gateway - User's Guide The attribute private management domain (prmd) set to IBMMAIL and the country code (FR for France, DE for Germany, IT for Italy etc) repre- sent the IBM/PROFS environment. prmd=IBMMAIL country=FR or DE or IT ... The attribute private management domain (prmd) set to EARN and the country code FR (for France where the gateway is located) represent the EARN environment. prmd=EARN country=FR Example: X.400 address of an IBMer in France country=FR admd=IBMX400 prmd=IBMMAIL surname=PINSE givenname=PINSED The attribute surname=PINSE is the user's surname and the attribute givenname=PINSED (in stead of Dominique) is created by IBM Mail Exchange. Example: X.400 address of an EARN/NJE user country=FR admd=IBMX400 prmd=EARN orgname=DBNGMD21 surname=GRZ027 Example: X.400 address of an Internet user: country=FR admd=IBMX400 prmd=EARN domain1t=RFC-822 domain1v1=Francois.Mitterrand(a)Elysee.fr In this example we use a domain defined attribute. Its name (RFC-822) is given by the key-word domain1t and its value is given by the key- word domain1v1. 15 EARN ADDRESSES There are two formats: EARN/NJE and Internet. Example of a pure EARN/NJE address: GRZ027 at DBNGMD21 With a pseudo Internet format: GRZ027@DBNGMD21.BITNET Example of a pure Internet address: Francois.Mitterrand@Elysee.fr ADDRESS CONVERSION Now, let's explain how the IBM/PROFS addresses are converted into X.400 addresses and how EARN addresses are converted into X.400 addresses. BETWEEN IBM/PROFS AND X.400 The conversions between IBM/PROFS and X.400 addresses are performed by the IBM Mail Exchange directory in which all EARN and IBM users must be registered to use the gateway. BETWEEN EARN AND X.400 The conversions between EARN and X.400 addresses are performed by the following simple mapping rules. For an EARN/NJE address, the userid is converted into the attribute surname and the nodeid into the attribute organization (org). For an Internet address, the whole address is put into a domain defined attribute named RFC-822. Some special characters are not accepted by X.400, and must be transformed. For example, the @ sign must be changed into (a). In both cases, the attributes: 16 IBM/EARN Gateway - User's Guide country=FR admd=IBMX400 prmd=EARN are added when converting EARN into X.400 and removed when converting X.400 into EARN. For an IBM/PROFS address, the X.400 attributes are converted into an Internet like address, as shown below: givenname.surname@ibmx400-countrycode.ibmmail.circe.fr where ibmmail.circe.fr identifies the IBM/EARN gateway in the EARN/Internet environment and ibmx400-countrycode identifies the access point of IBM Mail Exchange in the country. CONVERSION OF EBCDIC CHARACTERS Not yet available. 17