 |
| |
Installing and setting up FirstClass Server on Linux
About this document
This document is a supplement to the standard FirstClass administrator’s documentation set. Because FirstClass works seamlessly across platforms, most of the information you will need in order to use FirstClass on a Linux environment is available in those standard documents.
Although using FirstClass on Linux is very much like using FirstClass on any other platform, there are some differences in the way FirstClass is installed and configured on the Linux platform. This document provides the extra information specific to installing and configuring FirstClass in the Linux environment.
This document tells you how to:
• install FirstClass on Linux
This section provides requirements and instructions for installing the various FirstClass components.
• start your server and log in
This section explains how to start and log into your FirstClass system and what you will see on the administrator’s Desktop.
• configure your system on Linux
This section explains what the FirstClass installer configures on your system and what you need to check and configure after installation.
• migrate an existing FirstClass system to Linux
For those already using FirstClass, this section explains how to migrate an 8.0 FirstClass network store from a Mac OS X or Windows platform to Linux.
• administrate FirstClass on Linux.
This section provides some Linux-specific information helpful for the day-to-day operation of your FirstClass system.
The appendix describes file locations in Linux.
Installing FirstClass
You can install the FirstClass server and Internet Services on separate machines, or together on a single computer with either a single processor or multiple processors. The minimum requirements for each scenario are listed below, but the actual performance of your system will vary depending on how powerful your hardware is and how busy your system gets.
If you install the FirstClass server and Internet Services on two dissimilar machines, we generally suggest using the machine with the more powerful processor to run Internet Services. However, consideration should be given to the intended primary use of your system:
• If your system will be used primarily as a web server, Internet Services should be on the more powerful machine.
• If your server will be under a heavy load of FirstClass users, then you will want the server to be on the machine with the better disk system.
System requirements
System requirements for Linux server and Internet Services for Linux are found here: www.firstclass.com/products/SysReq/.
Installing the FirstClass server and Internet Services
Before installing FirstClass
Before you can install FirstClass you must create a user on your Linux system named “fcadmin” and log into the operating system as this user. The procedure varies depending on Linux distribution, but to do this on RedHat 9.0:
1 Log in as root.
2 Open System settings > Users and Groups.
3 Click Add User to open the New User form.
4 Enter fcadmin as the User Name.
 WarningIf you don’t give the user exactly this username, you won’t be able to install FirstClass.
5 Enter a Full Name for the user.
The full name you choose doesn’t matter, but we recommend (and this documentation will assume) the long name FirstClass Administrator.
6 Enter a password for the fcadmin account.
7 Click Ok.
8 Double-click the fcadmin user in the users list.
9 On the Groups tab select "adm".
 NoteDepending on the Linux distribution, the "adm" group may not already exist. If the group is not present in the list, add it and then make "fcadmin" a member of this group.
WarningIf you don’t do this fcadmin won’t have administrative level permissions and you won’t be able to install FirstClass.
10 Click Ok.
11 Log out.
Installing FirstClass
The installer will attempt to determine appropriate default settings for the System Profile and Internet configuration forms to allow the FirstClass server and Internet Services to work without further configuration. During the installation you will be asked to confirm these defaults. After installation, you should review these forms and verify that all configurations are correct. This process is essential and will not take much time.
Install FirstClass as follows:
1 Log in as fcadmin.
2 Download the installation file.
3 Open a Terminal window (Applications > System Tools > Terminal).
4 Navigate to the location to which you downloaded the installer file.
5 Enter: tar xzf filename
NoteThe filename must include its extension(s).
This will produce an installer script and a folder named “files”.
6 Type su to access the root account.
7 Enter the root password when prompted for a password.
8 Type ./installer to run the installer.
NoteThe ./ is required.
9 Respond to the prompts. In many cases, you need only hit <Enter> to confirm the default responses.
10 Press Ctrl-d or type exit to exit from the root shell and return to fcadmin when the installation is complete.
11 If you have not logged out since adding the "adm" group to the fcadmin account, you must log out and log back in as fcadmin before starting the FirstClass server.
During the installation you will be asked if you want to install the FirstClass server and if you want to install Internet Services.
• To install both on the same machine, accept the default [yes] in both cases.
• To install the FirstClass server and Internet Services on separate machines, repeat the installation process on both machines, selecting only the component you want to install on each machine.
The /opt/fcsd folder
The fcsd folder (/opt/fcsd) contains the server application and its supporting files. If you installed Internet Services on the same machine as the FirstClass server, the Internet Services files will also be in the folder. Otherwise, they will be in the corresponding fcsd folder on the Internet Services machine.
The /opt/fcsd folder is the equivalent of the FCServer folder on Windows and the /Library/FirstClass Server/ folder on Mac OS X.
Before logging into your FirstClass system, you may want to familiarize yourself with the contents of this folder. Also see FirstClass file locations on Linux for information about file locations for non-executable FirstClass files.
This folder contains the following folders and files:
• desktop folder
A folder containing the FirstClass objects which have been linked to the Linux desktop. These are the server and IS start and stop scripts and the status of FirstClass Services script.
• fcsd
The FirstClass core server executable.
• fcsd.rez
The FirstClass server executable's resources.
• fcslang.rez
The FirstClass language resource file.
• fcsd.log/fcsd.old files
These server log files are generated every time you start the server. The .log files contain detailed log entries from the latest run, and the .old files contain the output of the previous run. Because these files recycle every time you start the server, you lose the information after two restarts. Similar information is stored permanently in the server logs in /var/opt/fcsd/volumes/master/fcns/logfiles.
NoteIf you have had previous experience with FirstClass on another platform, you may be used to seeing the information that is recorded in these log files in the FirstClass server console. This information is also available from the Remote Console button on the Server Monitor form.
• fcfixvol
A utility used to properly set the initial permissions on the files and folders in a FirstClass network store after you copy the files from one volume to another or restore from a backup. (fclower.pl) that converts all network store file names to lowercase for use in the Linux file system.
• fclower.pl
A perl script used when executing fcfixvol -c all all that converts all network store file names to lowercase for use in the Linux file system.
• fcputil
The FirstClass fcputil executable.
• fcputil.fc
The FirstClass fcputil settings file, required to connect fcputil to the server.
Internet Services folders and files
The following folders and files are also in the /opt/fcsd folder if you installed Internet Services on this machine:
• fcisd
The FirstClass Internet Services executable.
• fcisd.rez
The Internet Services executable's resources.
• fcisd.log/fcisd.old
These IS log files are generated every time you start Internet Services. The .log files contain detailed log entries from the latest run, and the .old files contain the output of the previous run. Because these files recycle every time you start IS, you lose the information after two restarts.
Note If you have had previous experience with FirstClass on another platform, you may be used to seeing the information that is recorded in these log files in the Internet Services console or the console log files there.
• inetsvcs.fc
The settings file for Internet Services. This is preconfigured for 127.0.0.1 by default for systems with the FirstClass server and Internet Services on a single machine. If the FirstClass server and Internet Services are on two separate machines, this must be updated with the server’s IP address or name. See Configuring the inetsvcs.fc file for more information.
Starting your server and logging in
In order to do any system administration, whether from the server level or from the client, the server must be running. You will perform most administrative functions when you are logged into the client as the FirstClass administrator.
Starting your server
The FirstClass server application resides in /opt/fcsd. It is called fcsd (FirstClass server daemon). You can start fcsd directly but we recommend you use the FirstClass Server Start alias on the Linux desktop. There are aliases on the desktop for all of the following commands:
• FirstClass Server Start
• FirstClass Server Stop
• Internet Services Start
• Internet Services Stop
• Status of FirstClass Services.
You can also start, stop and check the execution status of the server and Internet Services manually with the provided shell scripts as follows:
1 Open a Terminal window (Applications > System Tools > Terminal).
2 Enter one of the commands below with the syntax /usr/sbin/fcsctl command.
If prompted for a password, enter the fcadmin user’s password.
Possible commands:
fcsctl
• /usr/sbin/fcsctl start
starts the server
• /usr/sbin/fcsctl stop
polite shutdown of the server (shutdown after all users have logged off)
• /usr/sbin/fcsctl force
fast shutdown of the server
• /usr/sbin/fcsctl status
checks server status (running/not running)
• /usr/sbin/fcsctl pause
pauses all mirrors
• /usr/sbin/fcsctl continue
continues all mirrors
• /usr/sbin/fcsctl help
lists possible fcsctl commands
fcisctl
• /usr/sbin/fcisctl start
starts Internet Services
• /usr/sbin/fcisctl stop
polite shutdown of IS (shutdown after all connections have logged off)
• /usr/sbin/fcsctl force
stops IS immediately
• /usr/sbin/fcisctl status
checks Internet Services status (running/not running).
• /usr/sbin/fcisctl help
lists possible fcisctl commands
Note Only the root user or machine administrators can start or stop the server or Internet Services. No matter who launches these programs, they will start up under the root user and admin group and will then fall back to the real context of the user who launched them, switching back to root-equivalent access only while opening reserved IP ports. Currently, only one user, fcadmin, is supported, so manually start the server and Internet Services only from that account.
Licensing FirstClass
After you install the FirstClass server, you can add optional licenses, such as user licenses.
 CautionAlways add the .KEY file first as it must be installed before other licenses are accepted.
To apply licenses:
1 Open the FC Update Service container on the administrator Desktop.
2 Select the document corresponding to the desired upgrade.
3 Click Apply Update.
4 Confirm that the upgrade was successful.
NoteAlthough we recommend applying licenses through the FirstClass Update Service, a .KEY license can also be added through the System Profile (Licensing tab) and any license can be applied using FirstClass scripting.
.KEY and .LIC files
There are two kinds of license files, .KEY files and .LIC files.
A .KEY license is a server license, and is the first license you add to your system. All other licenses are .LIC files and can be added in any order once the .KEY license has been applied.
 TipWe suggest that you license your server before configuring FirstClass. To configure FirstClass, you must log in as the administrator, and the first time you do this, you will be asked for licensing information in order to register.
Registering your server and licenses
When you log in as administrator for the first time, the online registration form will automatically open on the administrator’s Desktop. Click it to open it.
You must complete and send this form to Open Text to get access to online software and documentation updates and to be allowed to post support questions to our customer conferences. You can either email the completed preaddressed form (once FirstClass has been configured to send Internet mail) or print the form and mail it to one of the addresses indicated in the message body.
You do not have to complete all the fields on the form and some will already be filled in for you. The help text on the form explains which fields are optional. A copy of this form will be left on your Desktop for your future reference.
Once FirstClass receives your registration, you will be sent information on accessing our online system and given access to customer conferences.
Logging in as administrator
The FirstClass installation application adds a special user account for the administrator:
• the user ID is admin
• the password is admin
• the name is Administrator.
CautionTo preserve the security of your system, you should change the password for the administrator account as soon as you log in by choosing Collaborate > Change Password. Keep the new password confidential. We recommend that you not save the password in your settings file.
WarningYou can change the name, password, and user ID associated with the administrator account, but never delete this account. If you do, you won’t be able to log in as the administrator, and you will have to re-install your server. We suggest the administrator use a personal account for non-administrator tasks.
While you can log into the administrator account using a web-based client, you must use a FirstClass client to perform all administrative tasks.
Configuring your system on Linux
The FirstClass Linux installer automatically configures as much as possible, so that the FirstClass server and Internet Services just work immediately after running the installer. To do this, the installer tries to determine appropriate default settings for your System Profile and Internet configuration forms and asks you to confirm or alter those defaults during installation. In order to complete the configuration of your system, you should review those default values and adjust them for your individual situation as required.
Configuring the System Profile
To configure your system you must complete the System Profile form. For a complete explanation of all fields on this form, see our online help.
NoteYou must log in as the FirstClass administrator using the FirstClass client in order to configure your system.
To access the System Profile, select Admin > System Profile from the administrator’s Desktop.The default settings provided on this form are meant to meet the needs of the majority of users.
Use this form to specify the basic configuration information for your system. These values provide system defaults.
The form help (press F1 with the form as the active window) guides you through completing the form.
Configuring the Basic Internet Setup form
As it does with the System Profile form for the server, the FirstClass installer for Linux will auto-configure Internet Services as much as possible for you, so that it just works. However, you need to review the default values provided by the installer and adjust them and/or add to them for your individual situation as required.
You should review the Basic Internet Setup form to select the various Internet protocols on your system.
The Basic Internet Setup form is in the Internet Services folder on the administrator’s Desktop.
The form help (press F1 with the form as the active window) guides you through completing the form.
Configuring the Internet gateway form
Most administrators will not need to configure the Internet gateway form. You only need to configure this form if your site will use gateways. The Internet gateway form is in the Gateways folder on the administrator’s Desktop.
The form help (press F1 with the form as the active window) guides you through completing the form.
Configuring the inetsvcs.fc file
Internet Services and FirstClass server on same machine
If Internet Services is installed on the same machine as the FirstClass server, you can connect with either the local machine IP address of 127.0.0.1 (default), or with the specific domain name or IP address for that machine. However, you will still need to follow the configuration instructions below.
If Internet Services is installed on a different machine than the FirstClass server, you must enter the domain name or IP address of your server machine. This tells Internet Services where the FirstClass server is, enabling communication between the machines.
Configure the inetsvcs.fc file as follows:
1 Open the FirstClass client login form.
2 Click Browse and browse to /opt/fcsd/inetsvcs.fc.
3 Click Open to bring that information into the Login form.
4 Click Setup and configure the file to connect to the FirstClass server.
NoteThe password used must match the gateway password.
Administrating FirstClass on Linux
Once your FirstClass system is installed and configured, there is very little difference between running that system on Linux and running it on any other platform. That’s the nature, and the beauty, of FirstClass. You will find most of the information you will need to administrate your system on an ongoing basis in the online help. This section details some notable exceptions to that rule, providing you with details about what is different about administrating FirstClass in a Linux environment. To access the online help, choose Help > Contents from the FirstClass administrator's Desktop.
Using FirstClass volumes
Linux systems support the concept of mounting other volumes into arbitrary locations in the root file system folder tree, typically under the /mnt folder. The FirstClass server could use this list directly, however that would not be universally accurate under Linux. It would also remove the flexibility of allowing the FirstClass administrator to control which volumes are visible to FirstClass administrators and those who can open the Volumes list. This is important not only for security reasons, but also for performance reasons. It is important for the FirstClass administrator to be able to insert CDs and DVDs, or mount network volumes, without having these appear automatically to the FirstClass server.
The FirstClass Volumes list
The FirstClass server therefore allows you to define an explicit list of volumes accessible to the server. These need not correspond directly to physical drives, but could also be folders or symbolic links to any location visible in the Linux file system hierarchy. For this reason, they are referred to as logical volumes.
NoteAlthough logical FirstClass volumes can be symbolic links to any location, the fcns (FirstClass network store) folder in each volume and the files contained within that folder must be normal folders and files rather than symbolic links.
Logical FirstClass volumes are stored within the fcsd folder under /var/opt/fcsd/volumes/. Any folder (or symbolic link to a folder) in this volumes folder is considered to be a logical FirstClass volume, and will show up in the FirstClass Volumes list on the administrator’s Desktop. An additional entry corresponding to the root of the Linux file system will automatically appear in the FirstClass Volumes list.
Uses of logical volumes
In addition to being able to refer to multiple specific physical drives from FirstClass, logical FirstClass volumes can be used to partition users and/or conferences into logical groups, such as a separate logical volume for Internet news groups, that can later be split into separate physical devices. To do this physical split at a later date, you would move the files to the desired location and replace the FirstClass folder with a link to the other location in the file system.
Logical volumes also allow multiple formerly migrated server volumes to be merged onto one or more physical drives. To do this, put the network stores in separate folders under the Volumes folder.
And finally, they also leverage one of the greatest strengths of UNIX-based systems, the logical union of different objects under the single umbrella known as the root file system. Defining a FirstClass volume as either a folder in the file system or a link to an arbitrary location in the root file system allows for maximum flexibility.
Setting network store file permissions and ownership using fcfixvol
Any time you copy a network store from one volume to another or restore from a backup, you must afterward use the fcfixvol utility to set the permissions on the files and folders in the network store.
Use fcfixvol as follows:
1 Ensure you are logged in as fcadmin.
2 Open a Terminal window (Applications > System Tools > Terminal).
3 Enter the following at the prompt:
cd /opt/fcsd
4 Enter the following at the next prompt:
./fcfixvol <volume > <fcns>
NoteTo apply to all volumes, or all network stores on a volume, substitute “all” for either parameter. For example, to apply this command to all network stores on all volumes, use:
./fcfixvol all all
Other examples:
./fcfixvol master all
./fcfixvol master fcns8001
Running fcfixvol with a missing argument displays all possible values for that argument on that FirstClass system.
The process may take several minutes depending on the number and size of the network store volumes. The terminal will display the name of each network store it has recognized and tell you when it has finished setting the permissions and ownership on each.
Setting files to lowercase using fcfixvol
To also set all files to lowercase, add the argument -c (f./fcfixvol -c <volume > <fcns> )
Collecting activity statistics
FirstClass lets you collect daily server and Internet statistics on selected user activities. This can help you see how users are using their FirstClass environment and may also help when troubleshooting an ongoing system problem.
Information about the types of statistics you can track, how to specify which statistics you want to track and how to view user statistics files is available in our online help.
For FirstClass on Linux, the statistics folder path you set when completing the Statistics Control form must be an fcadmin:admin writable directory. The recommended path is
/opt/fcsd/stats.
After creating such a folder, configure this path in the server as follows:
1 Open the Reports folder on the administrator’s Desktop.
2 Double-click the Statistics Control form.
3 Enter the exact path in the Statistics folder path.
FirstClass file locations on Linux
It is recommended that you review and understand the ownership, nature, and location of the FirstClass files and folders (directories) on Linux. While familiarizing yourself with the FirstClass server for Linux, you may find it convenient to print this information and post it next to the server computer for reference.
"fcadmin" is the Linux user who executes and manages the FirstClass server and Internet Services. The fcadmin user belongs to the Linux admin group ("adm") and owns all of the files.
The FirstClass server (named fcsd) and Internet Services (fcisd) run as full-fledged UNIX daemons (services).
Locations:
• /opt/fcsd/
all executable-related files for both fcsd and fcisd
• /opt/fcsd/fcfixvol
a FirstClass network store utility to set file permissions and ownership and to convert file names to lowercase. May be executed at any time.
• /opt/fcsd/fcisd.log
/opt/fcsd/fcisd.old
current and prior Internet Services logs since launch, if IS installed on the computer
• /opt/fcsd/fcsd.log
/opt/fcsd/fcsd.old
current and prior server logs since launch. Equivalent to legacy Console to file.
• /opt/fcsd/inetsvcs.fc
Internet Services settings file, if IS is installed
• /var/opt/fcsd/volumes
a folder in which you can define an explicit list of logical FirstClass volumes accessible to the server. For information about FirstClass logical volumes and their uses, see Using FirstClass volumes.
• /var/opt/fcsd/volumes/master/fcns
the master logical volume
• /var/opt/fcsd/volumes/.../fcns
a secondary logical volume if present
• /var/opt/fcsd/volumes/.../fcns8001
the mirror logical volume if present
Any or all entries under /var/opt/fcsd/volumes/ may be links to other directories or volumes, but the actual fcns folders, and the folders underneath fcns, cannot be symbolic links.
NoteEnsure fcfixvol utility is run at least once on all logical FirstClass volumes before the server is launched.
• /opt/fcsd/stats
If desired, you must manually create this folder, as described in [Link]Collecting activity statistics. The above is the recommended path for this folder. It is not created by default.
• /usr/sbin/fcsctl
• /usr/sbin/fcisctl
the server and Internet Services control scripts used from a Terminal shell, and by the desktop icons. These are not normally visible from the Linux desktop.
NoteThis folder also includes many Linux system files that should not be modified or deleted.
• /mnt
usually lists all mount points for Linux volumes. Do not confuse /mnt with /var/opt/fcsd/volumes.
| ||