diff --git a/LDP/howto/docbook/Pine-Exchange.sgml b/LDP/howto/docbook/Pine-Exchange.sgml new file mode 100644 index 00000000..6e4fd8ac --- /dev/null +++ b/LDP/howto/docbook/Pine-Exchange.sgml @@ -0,0 +1,721 @@ + + +
+ + + + Pine-Exchange mini-HOWTO + + + Alexandru Roman <roma4386@rh.edu> + + v1.0, 2002-03-28 + + + + 1.0 + 2002-03-28 + ar + + Submitted to the LDP for publication. + + + + 0.3 + 2002-03-25 + ar + + Added the site-wide Pine Configuration information + + + + 0.2 + 2002-03-22 + ar + + Added Exchange v5.5 requirement, Pine v4.0 requirement, and + Acknowledgements Section. + + + + 0.1 + 2002-03-21 + ar + + Submitted to the LPD community/listserv for review. + + + + + + + + This HOWTO documents the configuration of the Pine email client to be + used with a Microsoft Exchange Server. + + + + + + + +Introduction + + +This HOWTO will provide you the required information on setting up Pine to +connect seamlessly to an Exchange Server. The services include the following: + + + + + The ability to send and receive email with Pine through an Exchange Server. + + + + + Access to all your Exchange INBOX and specialized folders and messages. + + + + + Configuration of specialized folders (Drafts, Sent Items, Public, etc). + + + + + Access to the Global Address List on the Exchange Server. + + + + + Seamless configuration meaning that you can switch between + Exchange/Outlook/Pine clients without any problems. (Pine will not mess up + your existing configuration if you wish to revert back to Outlook) + + + + + + +NOTE: This configuration will not allow you access locally created Exchange +files (ie. .pst, .pab, etc) + + + + + +Requirements + + +I assume if you are reading this HOWTO, you probably already meet the requirements, but here they are anyhow: + + + + + Have a working knowledge of the Pine email client (There is little to no + documentation in this HOWTO on using Pine). If you need more information + on using Pine, check out their main website. (see Resources) + + + + + A username/password in order to log into the Exchange Server (Exchange + servers run in a Microsoft domain, so your Exchange logon will be the same + as your domain logon). + + + + + Befriend the SysAdmin of your Exchange Server (You may or may not need the + help of this person depending on which services are running). + + + + + The Exchange Server must be version 5.5 or greater (Exchange did not + support IMAP until 5.5). + + + + + Pine started supporting IMAP with v2.0 and LDAP with v4.0. I would + recommend upgrading to the newest version, at the release of this document + v4.44 or at least v4.0 or greater. + + + + + + + + +Communication + + +These are the protocols that will facilitate communication between the Pine +client and the Exchange Server: IMAP, SMTP, and LDAP. (see Resources) + + + + + IMAP (Internet Message Access Protocol) - This protocol will provide you + access to all your messages and folders on the Exchange Server. + + + + + SMTP (Simple Mail Transfer Protocol) - This protocol will allow you to send + outgoing Internet email. + + + + + LDAP (Lightweight Directory Access Protocol) - This protocol will provide + you access to the Global Address List on the Exchange Server. + + + + + + + + +Exchange Server Configuration + + +Before starting to work on your Pine configuration, you must make sure that the +Exchange Server is configured correctly. This is where your SysAdmin comes in to +play. You need to make sure the IMAP, SMTP, and LDAP services are all running. +These services could potentially be running on separate servers, so you need to +consult your SysAdmin. + + + +On Exchange Server 5.5, IMAP and LDAP are installed and running in the default +installation. SMTP has to be installed separately, and comes in an add-on package +called Microsoft Exchange Connector, specifically for sending mail on the +Internet. + + + +NOTE: You can manually check to see if these services are running by telneting +to their respective ports. (ie. IMAP:143, SMTP:25, and LDAP:389) + + + + + +Pine Configuration + + +Pine has three types of configuration files we will concern ourselves with. Each +of them can contain all the same settings, but with varied syntax. The decreasing +order of precedence for each setting is as follows: /etc/pine.conf.fixed, +~/.pinerc, and /etc/pine.conf. Basically this means if Pine is looking for a +specific setting it first checks pine.conf.fixed, if it does not exist it checks +~/.pinerc, if it does not exist it finally checks /etc/pine.conf. + + + + + ~/.pinerc -- This is the local user copy of the configuration file. It is + located in the root of the users home directory it only affects that user. + You should use this configuration if you do not have superusers/root access + on the computer on which you are using Pine. To generate a new configuration + file of this type, you issue the command 'pine -pinerc .pinerc.new'. + + + + + /etc/pine.conf -- This is the site-wide Pine configuration file, so it + affects all the users running Pine on that machine (It can only be installed + by the superuser/root account). The syntax is slightly different than the + ~/.pinerc file since it has to represent all the users on the system, not + just one. To generate a new configuration file of this type, you issue the + command 'pine -conf > pine.conf.new'. + + + + + /etc/pine.conf.fixed -- This has exactly the same purpose and syntax as the + /etc/pine.conf file, except for one property. This file is not overridden + by the users ~/.pinerc file. Basically all the settings in this file are + enforced, and cannot be changed by the user. Initially this file should be + empty. You should add settings to it as needed. + + + + + + +Each of these files contain settings in the form of "key=value" pairings. You +can change these settings with your favorite editor (ex. vi). For the ~/.pinerc +file the user can change the settings directly from Pine, by going into (S)etup +then (C)onfig. For LDAP settings go into (S)etup then (D)irectory. + + + +Here are the important settings for communicating with the Exchange Server: + + + +NOTE: The syntax of each setting will be shown in the Example configuration. + + + + + user-domain -- The domain name portion of your email address (So if your + email address is user@yourcompany.com, then yourcompany.com would be + your user-domain). + + + + + + customized-hdrs -- This is the actually "From:" header that will appear in + the message that you compose before you send it out. If you don't specify + this header, the user and full name are taken from the system + /etc/passwd file. There are other variations to setting up the "From:" + header (see Resources). + + + + + + smtp-server -- The hostname of your SMTP server. This may or may not be the + same as your Exchange Server. (With SMTP Authentication you will need to + specify a "/user" parameter on the end of this setting). + + + + + + inbox-path -- This contains the default path to your INBOX. (This should + point to the remote INBOX on your Exchange/IMAP server). + + + + + + folder-collections -- This contains points to other folder collections you + wish to view. There are only two sets you should concern yourself with. + The first is your INBOX folders (personal folders you create in your + INBOX), and the second is your Mailbox folders, which are default folders + (ie. Sent Items, Deleted Items, Drafts, Outbox, Public Folders, etc.) + + + + + + default-fcc -- This folder contains a carbon copy of all messages that you + sent out. (This should point to the "Sent Items" folder on the Exchange + server) + + + + + + postponed-folder -- This folder contains postponed messages, that you wish + to finish later. (If you are using Outlook, this should point to the + "Drafts" folder on the Exchange server, otherwise you can create your own + on the server) + + + + + + ldap-server -- This is the hostname of your LDAP server. There are many + parameters available for which you should consult your Pine documentation. + (This will be used to access the Global Address List on the Exchange + Server). + + + + + + rsh-open-timeout -- Pine will use rsh to connect to IMAP by default. + This is an Integer value which represents the timeout period. (Since + Exchange servers don't run rsh, we are going to want to disable this + feature by setting this value to 0). + + + + + + + +One potential problem that you may run into is SMTP Authentication. Basically, +this means that you need to provide a username and password to use SMTP to send +email. I have found no official documentation which states that Pine supports +SMTP Authentication (more so on the contrary). The closest thing I've found is +the possibility of a /user Parameter to the smtp-server setting, which was +mentioned briefly in the change log from version 4.20 to 4.21. It was also +brought up a couple of times on the listserv. (see Resources) + + + +If you still have problems with it, here is an alternative which I ended up +using. You can have your SysAdmin add your IP address to the Exchange +Server to allow you to bypass the SMTP authentication. + + + + + +Example Configuration + + +This example should help carify the syntax of the settings defined in the +previous section, with a set of artificial data. + + + +Gather your information + + +Let us assume the following default information (You may provide your own +if you have it available): + + + + + Printed Name = "Foo Foo" + Account/User Name = "foofoo" + Domain Name = "foofoo.org" + Exchange/IMAP/LDAP Server = "192.168.1.25" + + + + +NOTE: In order for the transition to be seamless, you have to make sure you +match the information precisely as it is stored on the Exchange Server. (ie +if your name on the Exchange server is "John B. Doe", make sure you set your +printed name to the exact value) + + + +Let us also assume, you have been using Outlook up to this point, and you have +accumulated some messages in your "INBOX", "Sent Items", and "Drafts". Not too +mention a couple of personal folders you created in your "INBOX" on the server +to categorize your mail: "TODO", "DONE", and "Personal". + + + + +Setting up a local ~/.pinerc configuration file + + +Here are the settings you should find in your ~/.pinerc file. In most cases, each +setting will be empty (ie "key=" with no value specified). Here is what they +would look like plugging in the default information. + + + + + user-domain=foofoo.org + smtp-server=192.168.1.25 + inbox-path={192.168.1.25/user=foofoo}INBOX + folder-collections="INBOX Folders" {192.168.1.25/user=foofoo}inbox/[], + "Mailbox Folders" {192.168.1.25/user=foofoo}[] + default-fcc="{192.168.1.25/user=foofoo}Sent Items" + postponed-folder={192.168.1.25/user=foofoo}Drafts + customized-hdrs=From: Foo Foo <foofoo@foofoo.org> + ldap-servers=192.168.1.100 "/base=/impl=1/rhs=0/ref=0/nosub=0/type= + /srch=contains/time=/size=/cust=/nick=/matr=/catr=/satr=/gatr=" + rsh-open-timeout=0 + + + + +NOTE: If you want to try SMTP Authentication with the above configuration, you +would replace: + + +smtp-server=192.168.1.25 + + +with: + + +smtp-server=192.168.1.25/user=foofoo + + + + + + + +Setting up a site-wide Pine configuration + + +This configuration affects all the users on the system and requires a bit more +work to setup. Only a UNIX SysAdmin should attempt this configuration. + + + +NOTE: In order for this configuration to work properly, the Microsoft domain +account information must be synced up with the Unix account information +(ie. usernames and full names must match). + + + +Looking at the default provided information you should notice that "Printed Name", +and "Account/User Name" now have to be generalized. For "Printed Name", in +removing it from the configuration file, Pine will default to the personal name +found in the /etc/passwd file. For "Account/User Name", you can use "${USER}", +which points to the environment variable which holds the users login name. So +with that you get the following configuration: + + + + + user-domain=foofoo.org + smtp-server=192.168.1.25 + inbox-path={192.168.1.25/user=${USER}}INBOX + folder-collections="INBOX Folders" {192.168.1.25/user=${USER}}inbox/[], + "Mailbox Folders" {192.168.1.25/user=${USER}}[] + default-fcc="{192.168.1.25/user=${USER}}Sent Items" + postponed-folder={192.168.1.25/user=${USER}}Drafts + #customized-hdrs=From: Foo Foo <foofoo@foofoo.org> + ldap-servers=192.168.1.100 "/base=/impl=1/rhs=0/ref=0/nosub=0/type= + /srch=contains/time=/size=/cust=/nick=/matr=/catr=/satr=/gatr=" + rsh-open-timeout=0 + + + + +NOTE: In this configuration we want to comment out the "customized-hdrs" setting +since we want the user information to be retrieved from the system /etc/passwd +file. + + + +The last step in this configuration is determining whether to put the settings +in /etc/pine.conf or /etc/pine.conf.fixed. That choice is yours, and depends +on how much control you need to give to the users. If your company only +uses Exchange, maybe all the settings should go in fixed, but then users couldn't +use Pine for anything else. Remember, if you put a setting in pine.conf.fixed, +the user does not have the option to change it. + + + + + +Logging into the Exchange/IMAP server + + +When you first start up Pine, with your new configuration file (You can use the +command 'pine -p .pinerc.new-config' if you have multiple), Pine will +automatically try to connect to your Exchange/IMAP Server. After establishing a +connection, using the provided username from the configuration file, it will +prompt you for your password. This will be your network logon password on the +Microsoft domain. Once you get authenticated, you should be ready to go. + + + + +Accessing your Folders with IMAP + + +When you first open your folder list, you should see three folder collections. +Incoming Folders(INBOX), INBOX Folders(personal folders), and Mailbox Folders +specialized folders). + + + +Even though this is not a Pine HOWTO, there is one thing I want to point out +about navigating the folders. When viewing the contents of a folder, if you want +to view the list of messages in the folder, hit the "ENTER" key, if you want to +view the list of folders(subdirectories) in the folder, hit the ">" key. If you +need more information on using Pine, check out their website (see Resources). + + + + +Accessing your Global Address List with LDAP + + +Using the default configuration provided in this example, when you compose a +new message, and type in a name in the "To:" box. Pine will first check your +local addressbook for the nickname. If it doesn't find it, it will then run an +LDAP query by default, using the default name you typed as the search string. +Depending on the speed of the LDAP server, you should get a response +relatively quickly. From the results you can choose the entry you were looking +for, and continue writing your email. + + + +NOTE: If you type in an email address in the "To:" box, it will NOT do an LDAP +search or any other addressbook search (ie. user@smtp.email.org). + + + +If you just want to do a search, without actually composing a new message, you +can go directly to your addressbook, select the LDAP server, and type the +search string from there (ie (M)ain, (A)ddressbook). + + + +In case you do not want Pine to do an automatic LDAP lookup everytime you +compose a new message, you can change the parameter "/impl=1" in the +"ldap-server" setting to "/impl=0". This will allow you to do a manual LDAP +query if you wish. + + + + +Sending an email with SMTP + + +This procedure does not change from normal Pine usage. You can start composing +your message right away. When you send the message it will get sent through the +provided SMTP server. + + + + + + +Resources + + + + + + + Pine Information Center + + + + + Pine mailing list + + + + + Pine Frequently Asked Questions + + + + + Current Pine Distribution Documentation + + + + + Pine Version Changes + + + + + Changing Your From Header in Pine + + + + + Internet Message Access Protocol + + + + + Lightweight Directory Access Protocol + + + + + Simple Mail Transfer Protocol + + + + + SMTP Authentication RFC + + + + + + + + + +Acknowledgements + + +Thanks to Hugo van der Kooij for mentioning that Exchange version 5.5 or greater +was not in the Requirements section. Thanks to Y Giridhar Appaji Nag for +suggesting I add support for a Site-Wide Pine configuration. + + + + + + +Disclaimer + + +Use the information in this document at your own risk. I disavow any +potential liability for the contents of this document. Use of the +concepts, examples, and/or other content of this document is entirely +at your own risk. + + + +All copyrights are owned by their owners, unless specifically noted +otherwise. Use of a term in this document should not be regarded as +affecting the validity of any trademark or service mark. + + + +Naming of particular products or brands should not be seen as +endorsements. + + + + + +Copyright + + +Copyright (c) 2001-2002 by Alexandru Roman + + + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license may be found at: + + + +http://www.gnu.org/copyleft/fdl.html + + + +It is requested that the author's name and email are retained on all +copies of this document. It is requested that corrections and/or comments +be forwarded to the author. It is requested that the author be notified of +any redistribution, derivation, and/or incorporation of this document. + + + + +
+ +