May 2001
This edition applies to Version 5.5 of the VisualAge Smalltalk products, and to all subsequent releases and modifications until otherwise indicated in new editions. Make sure you are using the correct edition for the level of the product. The term "VisualAge", as used in this publication, refers to the VisualAge Smalltalk product set.
Portions of this book describe materials developed by Object Technology International Inc. of Ottawa, Ontario, Canada. Object Technology International Inc. is a subsidiary of the IBM(R) Corporation.
If you have comments about the product or this document, address them to: IBM Corporation, Attn: IBM Smalltalk Group, 621-107 Hutton Street, Raleigh, NC 27606-6324. You can fax comments to (919) 828-9633.
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the information in any way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 1999, 2000, 2001. All rights reserved.
U.S. Government Users Restricted Rights -- Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
What's New in Version 5.5 Installation
What's New in Version 5.5.2 Installation
Installing VisualAge Smalltalk
Setting up team programming with EMSRV
EMSRV for Windows NT(R) and Windows 2000
EMSRV for UNIX operating systems
References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of the intellectual property rights of IBM may be used instead of the IBM product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designated by IBM, are the responsibility of the user.
IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, 500 Columbus Avenue, Thornwood, NY, USA 10594.
IBM may change this publication, the product described herein, or both.
The following terms are trademarks of the IBM Corporation in the United
States, other countries, or both:
| AIX(R) |
| IBM |
| OS/2(R) |
| VisualAge(R) |
The following terms are trademarks of other companies:
| Windows(R) | Microsoft(R) Corporation |
| UNIX(R) | The Open Group |
Windows is a trademark of Microsoft Corporation.
UNIX is a registered trademark of The Open Group in the United States, other countries or both.
Other company, product and service names may be trademarks or service marks of others.
This book guides you through installing VisualAge Smalltalk and its associated features.
This book also covers setting up a team development environment, including information on setting up and using EMSRV, the library management server.
This book is written for anybody who needs to install VisualAge Smalltalk. It is also intended for administrators, or anyone who might be maintaining the library server for a team development group.
This book uses conventions that you might not have seen in other product manuals.
These highlighting conventions are used in the text:
| Highlight style | Used for | Example |
|---|---|---|
| Boldface | New terms the first time they are used | VisualAge uses construction from parts to develop software by assembling and connecting reusable components called parts. |
| Items you can select, such as push buttons and menu choices | Select Add Part from the Options pull-down. Type the part's class and select OK. | |
| Italics | Special emphasis | Do not save the image. |
| Titles of publications | Refer to the VisualAge Smalltalk User's Guide. | |
| Text that the product displays | The status area displays Category: Data Entry. | |
| VisualAge programming objects, such as attributes, actions, events, composite parts, and script names | Connect the window's aboutToOpenWidget event to the initializeWhereClause script. | |
| Monospace font | VisualAge scripts and other examples of Smalltalk code |
doSomething | aNumber aString | aNumber := 5 * 10. aString := 'abc'. |
| Text you can enter | For the customer name, type John Doe |
Please take a few moments to tell us what you think about this book.
The only way for us to know if you are satisfied with our books or if we can
improve their quality is through feedback from customers like you. A
reader's comment form is available on our VisualAge Smalltalk Web site.
What's New in Version 5.5 Installation
The look and feel of the install program has changed somewhat since version 5.0. Please refer to the installation instructions for your operating system for steps on how to install.
In past VisualAge Smalltalk installs it was necessary to separately install your .dat files based on the which features you added to the base install. Version 5.5 supports pre-importing feature code libraries at install time so that this is no longer necessary, all the .dat files are automatically loaded at the same time the feature is installed.
In Version 5.0, the .ctl files on the Client determined what you could view in the Load/Unload dialog. In Version 5.5, this has changed; the Library Manager now determine what you will view in the Load/Unload dialog. This change makes it essential for you to keep your Client code in sync with the code installed on the Library Manager.
For example, Mary installs UML designer on the Manager and John installs just the base client. In the load/unload dialog, John sees that UML classes are available for loading and does so. The load of the classes will work correctly. When John attempts to use the UML designer classes, he will encounter unpredictable results due to missing files such as mprs, cats, dlls, etc.
For optimum performance it is ideal that your manager and client
installations have the same features loaded. Please see your system
administrator in order to determine which features have been loaded onto the
manager.
VisualAge Smalltalk Enterprise Version 5.5.2 is a refresh of
VisualAge Smalltalk Enterprise Version 5.5 and includes fixes to known
defects, along with several enhancements. See the readme
file for additional details.
If you have previously installed VisualAge Smalltalk Version 5.5 or
5.5.1, the Select Features page will display a + and
a number to the right of each feature in order to indicate Version 5.5
or 5.5.1 features that were previously installed and the
approximate size difference of the feature in VisualAge Smaltalk Version
5.5.2.
If you have previously installed VisualAge Smalltalk Version 5.5 or
5.5.1 Manager and are installing VisualAge Smalltalk Version
5.5.2 Manager, the Verify Development Manager page
appears. You must verify or type the hostname or manager library path
of the manager that you wish to update. A second Verify Development
Manger screen then appears. You must ensure that you have backed up the
Development Manager library and check the I have backed up my manager
library box.
After installing VisualAge Smalltalk Version 5.5.2 Client,
you will have three new directories; icsrn552,
icspk552, and image552.
You will also have a new program link for the IBM VisualAge Smalltalk
Enterprise Client Development Image 5.5.2.
You are no longer required to build your own IBM Smalltalk Image.
Version 5.5.2 provides a prebuilt IBM Smalltalk image:
What's New in Version 5.5.2 Installation
Updated Select Features Page
Verify Development Manager Page
New Directories and Startup Option
IBM Smalltalk Image Provided
This chapter guides you through installing VisualAge Smalltalk on Windows,
OS/2, and UNIX platforms. If you are migrating from a previous version
of VisualAge Smalltalk, please refer to the VisualAge Smalltalk Migration
Guide before starting the installation.
For VisualAge Smalltalk Version 5.5.2, you do NOT need to
install VisualAge Smalltalk Version 5.5 or 5.5.1 before
you install Version 5.5.2. Version 5.5.2
determines if Version 5.5 or 5.5.1 is installed on your
machine and does one of the following:
There are two pieces to the installation of VisualAge Smalltalk: the
library manager and the client. The library manager is the repository
that holds all of your Smalltalk code. The client consists of visual
programming tools and communication links to the server where the library
manager is installed.
To install VisualAge Smalltalk in a team development environment, a system
administrator should install the library manager on a network attached server
computer. The individual developers can then install the client code
locally on their machine and connect to the library manager using
EMSRV. When you install VisualAge Smalltalk this way you will be asked
during installation to specify the name of the server and the location where
the library manager is installed on the server.
If you are working independently of other developers you can install both
the library manager and the client code on one machine, and connect from the
client to the manager using file I/O access. This is also referred to
as a standalone installation.
See the readme file for information on downloading VisualAge
Smalltalk Enterprise Version 5.5.2 Manager and Client.
You must download and install both the Version 5.5.2 manager and
the Version 5.5.2 client.
Installing VisualAge Smalltalk Enterprise Version 5.5.2
Overview of installation
Downloading VisualAge Smalltalk Enterprise Version 5.5.2
Before installing Version 5.5.2, do the following:
c:\temp\cd_m\install_w\setup.exe
where c:\temp is the temporary directory in which you unzipped the VisualAge Smalltalk Version 5.5.2 files.
c:\temp\cd_c\install_w\setup.exe
where c:\temp is the temporary directory in which you unzipped the VisualAge Smalltalk Version 5.5.2 files.
c:\temp\cd_m\install_o\install.cmd
where c:\temp is the temporary directory in which you unzipped the VisualAge Smalltalk Version 5.5.2 files.
c:\temp\cd_c\install_o\install.cmd
where c:\temp is the temporary directory in which you unzipped the VisualAge Smalltalk Version 5.5.2 files.
The library manager holds your VisualAge Smalltalk source code. The VisualAge Smalltalk Enterprise - Library Manager should be installed before installing VisualAge Smalltalk Client. You can either install the library manager on a network server and connect using EMSRV for team programming, or you can install the library manager on your local machine and connect to the repository using File I/O access or EMSRV if it is supported on your operating system. This section covers installing a library manager on a server as a repository for team development.
When you install the manager, the .dat files which provide the additional code for the VisualAge Smalltalk features are automatically imported into your Library Manager.
To install the VisualAge Smalltalk Enterprise - Library Manager, do the following:
You must set up and start EMSRV after you install the library manager. Clients cannot connect to the library manager until EMSRV is running.
To set up and start EMSRV for Windows NT/2000, see the following sections:
To set up and start EMSRV for OS/2, see the following sections:
Before installing a VisualAge Smalltalk Enterprise Client for team development, you need to know some information about where the library manager is installed. EMSRV is used to connect to the library manager which is installed on a network server for team development. The EMSRV environment is set up during the install for the VisualAge Smalltalk Client. The library administrator should provide the following information about the VisualAge Smalltalk library manager:
To install a VisualAge Smalltalk Client do the following:
For example, if the manager is installed on a machine named vastmgr in the directory f:\vastv55\manager\mgr55.dat. Even if you have vastmgr mapped as M:on your computer, you would specify f:\vastv55\manager\mgr55.dat as the path on the server where the library manager is installed.
Installing a VisualAge Smalltalk standalone development environment consists of two steps. The first step is to install the VisualAge Smalltalk Enterprise - Library Manager. Then you install the VisualAge Smalltalk Client.
The library manager holds your VisualAge Smalltalk source code. The VisualAge Smalltalk Enterprise Library Manager should be installed before installing VisualAge Smalltalk Client. For a standalone development environment, you install the library manager on your local machine and connect to the repository using File I/O access, or you can use EMSRV if it is supported on your operating system. This section covers installing the library manager for standalone development using File I/O access.
To install the VisualAge Smalltalk Enterprise - Library Manager, do the following:
Before installing a VisualAge Smalltalk Client, you need to know some information about where the library manager is installed. For a standalone install, the library manager is installed on your local machine.
To install a VisualAge Smalltalk client, do the following:
If you have purchased VisualAge Smalltalk Enterprise, you must unlock the product after you install. If you do not unlock the product, you will be using an evaluation version of the product, which will not let you save your image after 30 days.
To unlock VisualAge Smalltalk Enterprise, or any of the purchased features, first start the Unlock utility. Through your Start Menu/Program Files/IBM VisualAge Smalltalk Enterprise Client 5.5/5.5.1 open your Unlock utility. Then do the following:
The Unlock utility now lists the VisualAge Smalltalk Enterprise development products you can unlock.
The Unlock utility confirms that the product is unlocked or provides hints on why the product isn't unlocked.
You must unlock each product you have purchased. If you load an evaluation feature into your image, even if you have unlocked VisualAge, your image will become an evaluation image. When you unload the evaluation feature, your image will still be an evaluation image. For this reason, be sure to unlock all features you have purchased before you load them into your image.
The Version 5.5.2 installation automatically merges the Version 5.5.2 code into the Version 5.5 or 5.5.1 manager.
If you had previously installed Version 5.5 or 5.5.1, before you use VisualAge Smalltalk Version 5.5.2, do the following:
To uninstall VisualAge on Windows,
To uninstall VisualAge on OS/2, do the following:
This section guides you through installing VisualAge on UNIX.
The library manager holds your VisualAge Smalltalk source code. The VisualAge Smalltalk Enterprise - Library Manager should be installed before installing VisualAge Smalltalk Client. The Manager should be installed first, on a server accessible by those application programmers who will be using VisualAge. The Manager can be installed just once, by a system administrator. The client should be installed by the system administrator on each workstation.
To install the VisualAge Smalltalk Enterprise - Library Manager, do the following:
The files are installed to /opt/IBMvast/5.5 directory.
The size of the library manager will grow considerably as optional features are loaded and as source code accumulates during the course of a development effort. It is possible to install the library manager on a filesystem other than /opt, and to run the EMSRV daemon with the library manager on the alternate filesystem. This may be a convenient configuration for managing the growth of the library manager and for maintenance backups.
To install the library manager on an alternate filesystem you must complete a couple of steps manually. Before performing the install, create a /opt/IBMvast/5.5/manager filesystem which is mounted on a logical volume other than the volume on which /opt is mounted, or define /opt/IBMvast/5.5/manager as a symbolic link to a directory on such an alternate filesystem.
If you are using EMSRV, you must set up and start EMSRV after you install the library manager.
Before installing a VisualAge Smalltalk Client, you need to know some information about where the library manager is installed.
You can use EMSRV to connect to the manager. The EMSRV environment is set up during the client install.
The library manager administrator should provide the following information about the VisualAge library:
To install a VisualAge Smalltalk client, do the following:
The files are installed to /opt/IBMvast/5.5 directory.
If you have purchased VisualAge Smalltalk Enterprise - Client or any of its associated features, a system administrator must unlock the product after install. If the product is not unlocked, you will be using a evaluation version of the product, which will not let you save your image after 30 days.
To unlock VisualAge, or any of the purchased features, in your CDE FileManager, change to the /opt/IBMvast/5.5/unlock directory. Double-click on abtunlck, then do the following:
The Unlock utility now lists all of the VisualAge products you can unlock.
The Unlock utility confirms that the product is unlocked or provides hints on why the product isn't unlocked.
You must unlock each product you have purchased. If you load an
evaluation feature into your image, even if you have unlocked VisualAge, your
image will become an evaluation image. When you unload the evaluation
feature, your image will still be an evaluation image. For this reason,
be sure to unlock all features you have purchased before you load them into
your image.
The Version 5.5.2 installation automatically merges the
Version 5.5.2 code into the Version 5.5 or
5.5.1 manager.
If you had previously installed Version 5.5 or 5.5.1,
before you use VisualAge Smalltalk Version 5.5.2, do the
following:
After installing VisualAge Smalltalk Version 5.5.2
Before you can start VisualAge you must configure your installation.
The Smalltalk image start-up configuration file includes statements which may need to be tailored to your network configuration. The file, abt.ini, is located in the /opt/IBMvast/5.5/newimage directory.
The following IP host specifications must be verified or modified in your /opt/IBMvast/5.5/newimage/abt.ini file according to your configuration.
ServerAddress=
They are expected to contain the host name or dotted-decimal IP address of the host where the server component of the product was installed.
The VisualAge manager component uses a daemon to manage concurrent access to library and import files. This program is named EMSRV.
To start the EMSRV process, do the following:
This shows you the device number of the mgr55.dat file. The message might read The device number of /opt/IBMvast/5.5/manager/mgr55.dat is 64.
For example, using the device number returned in the previous step, type /opt/IBMvast/5.5/bin/emsrv -xd64
For more options on starting EMSRV, type emsrv -h at a command prompt.
Each VisualAge Smalltalk developer requires certain files in their own working directory. A copy of the appropriate files may be obtained by running the program /opt/IBMvast/5.5/bin/vasetup.
When you run vasetup VisualAge Smalltalk copies the master abt.ini file to your working directory. If the system administrator makes any additional changes to the master abt.ini file, for example unlocking the Client Base or any features, the copy of abt.ini that is in your working directory will not match the master abt.ini in /opt/IBMvast/5.5/newimage. If the administrator unlocks components in the master abt.ini file, but those components are not unlocked in your abt.ini you can do one of two things:
As of Version 5.5, you no longer are required to uninstall any previous releases of VisualAge Smalltalk, prior to installing VisualAge Smalltalk on UNIX. If you decide that you are going to uninstall a previous version, please follow the directions noted:
Before you uninstall a previous version of VisualAge Smalltalk on UNIX, do the following:
To uninstall a previous version of VisualAge Smalltalk on AIX, do the following:
A window appears, showing the actual AIX command being executed and a log of execution status. The command text is also written to the file smit.script, and the log text is written to the file smit.log.
cd /opt/IBMvast/5.5/inst ./uninst_client
cd /opt/IBMvast/5.5/inst ./uninst_manager
The following drawing shows the client and server components that
make up a VisualAge Smalltalk Enterprise team development environment.
Connectivity is provided by a TCP/IP network.
Any computer where a shared repository will reside must be a server,
which is to say it must run the repository server program (EMSRV).
There may be more than one server in your environment. Each server has
the following components:
VisualAge Smalltalk Enterprise clients have the following
components:
EMSRV is the program that manages concurrent access to shared repositories on the server. It uses native locking calls to manage file input/output requests against the library files on the server. The administrator must start the library server, using the emsrv command, before clients can connect to the shared library. The administrator then uses the EMADMIN utility to manage the library server.
To enable team programming with VisualAge Smalltalk, the library server (EMSRV) must be installed on any computer where one or more shared repositories will reside. You may have one or more library servers in your team development environment. Below are some issues to consider when planning where to install shared repositories and the library server.
The EMSRV client process runs automatically on VisualAge Smalltalk Enterprise clients.
Run EMSRV on server-class computers. For optimal availability and performance, servers should be dedicated; that is, shared repositories should not reside on a developer's workstation.
EMSRV supports repositories of up to 16 GB. The actual size limit may be smaller depending on the capabilities of the file system or operating system where EMSRV is running. Refer to the VisualAge Smalltalk web page for more information.
VisualAge Smalltalk Version 5.5.1 supports EMSRV Version 6.23 or higher. If you have a server that is running EMSRV code prior to EMSRV Version 7.0, the EMADMIN 7.0 utility will not work. For example, if your server is running EMSRV Version 6.24, you cannot use EMADMIN Version 7.0 with that server. We recommend that you upgrade to the latest versions of EMSRV and EMADMIN.
EMSRV for Windows NT/2000 and NetWare use one thread per client connection. This means that EMSRV readily scales to support more connections on these platforms. EMSRV automatically spawns threads to handle client connections.
EMSRV for OS/2 or UNIX only use one process per client connection. This means that EMSRV performance degrades slightly as the number of connections increases.
EMSRV uses TCP/IP for its client/server network connections. The default limit for client connections to a server is 256. The default limit for client connections can be changed by using the -M command line option when starting EMSRV. Theoretically, the number is bounded primarily by memory, but testing has shown that some TCP/IP stacks will run out of stream sockets before this limit of memory is reached. Typically, this number is greater than one hundred but it varies with each stack.
The default port number for the EMSRV server and client connections is 4800. This can be changed by using a command line parameter when starting EMSRV, when running EMADMIN, and when connecting from the development client to EMSRV.
The team development server requires the following files:
The server repositories must reside on the same computer as EMSRV. EMSRV does not support accessing a library on a remote file system.
EMSRV code is installed when you install the VisualAge Smalltalk Enterprise manager library or client. For information about starting EMSRV, see the appropriate section for your operating system:
All files created by the library server are owned by the EMSRV user. The library server has the file access rights of the EMSRV user. To ensure the integrity of shared repositories, you may wish to restrict rights for library files to the EMSRV user.
In the team development environment it is quite common for the shared library to grow very large, over several hundred megabytes. You should ensure that the library is stored on a computer that can handle this type of load.
VisualAge Smalltalk supports three levels of user validation. These levels consist of the following:
Native passwords can be used on all platforms except OS/2.
If you intend to maintain VisualAge Smalltalk user IDs on your site, you must create and maintain a passwd.dat file in the working directory.
This file contains the logon user IDs of all users and their respective passwords for VisualAge Smalltalk. The VisualAge Smalltalk passwords should not be the users' actual logon passwords. The format of the file is one user ID and password per line, with the user ID first, followed by a single space and the password.
The following shows an example of a passwd.dat file:
fred mypassword barney secret wilma hello betty ZXF6
When setting up a repository, you will be prompted for a supervisor password. As the system is installed off the CD, there is a single user defined, the Library Supervisor. You must specify the Library Supervisor's password when connecting the client to the server for the first time.
If you are using passwd.dat checking, you can look in that file to locate the Library Supervisor's password. If there is not a password specified, you may at this point add one.
If you are using network password authentication, your domain controller will need to have 'supervis' (the network name of Library Supervisor) defined as a valid user.
If you want to use native password authentication but do not want to
define a network userid of 'supervis', then you should perform the
following steps:
Most native authentication services on UNIX platforms offer multiple
options for configuration. The simplest form of native authentication
on UNIX platforms is the local password file (usually /etc/passwd)
which contains passwords encrypted with a one-way encryption function.
Although the passwords cannot be decrypted, the file is readable by all users
of the system and therefore susceptible to dictionary-based password cracking
attempts.
The simplest alternative to the local password file is password
shadowing. On systems that use NIS/yp or password shadowing, replace
each encrypted password in the /etc/passwd file with a special
token and store the passwords in a separate file not readable by normal system
users.
Previous releases of EMSRV for UNIX platforms supported local password
files and shadow passwords by using two separate EMSRV executables:
emsrv and emsrv.shadow. This was necessary
because each authentication system uses a different programming
interface.
Recent releases of most UNIX platforms now offer a single authentication
programming interface that can support both of the aforementioned
authentication systems as well as many others. The most well-known of
these authentication frameworks is PAM (password Authentication
Modules). PAM was developed by Sun Microsystems and is now supported by
and ships as part of Solaris, Linux, and HP-UX. Although there is no
PAM implementation included with AIX, IBM offers a similar
authenticate() function that can be used to authenticate users
using local password files, shadow passwords, and DCE authentication.
A single authentication programming interface makes it possible for one
EMSRV executable to use a variety of authentication systems. For this
reason, there is no longer an emsrv.shadow available on some
UNIX platforms. In such cases, the emsrv executable can be
used to authenticate using shadow passwords and, potentially, other forms of
authentication as well.
Where EMSRV uses an authentication framework such as PAM, the
authentication system used by EMSRV and its exact configuration, are
determined by the environment. For example, EMSRV for Linux uses PAM
and, therefore, requires the file /etc/pam.d/emsrv to be
present and to specify the PAM (module) used by EMSRV.
On Linux and Solaris platforms, authentication is implemented using PAM
(password Authentication Modules). Although this would theoretically
allow the use of any PAM (modules) with EMSRV by changing the relevant PAM
configuration file, in practice this is not possible.
EMSRV does not converse with clients in a manner that is entirely
compatible with the PAM architecture, As a result, EMSRV authentication will
only work where the module prompts initially for a text password (supplied
initially by the client). The tested and certified authentication
methods meet these requirements as will most PAM (modules).
Sophisticated modules that require extended conversation or authentication
data that EMSRV does not support, will not work correctly with EMSRV.
Fingerprint scanners and retina scanners are such examples.
EMSRV for AIX now supports authentication using the system
authenticate() function. This allows one EMSRV executable to
support both shadowed and non-shadowed passwords in addition to DCE
authentication.
The authentication method for each user is set in the
/etc/security/user file.
EMSRV for HP-UX continues to implement authentication using two separate
EMSRV executables. Although HP-UX 11.0 supports PAM, there is a
bug in the implementation that is identical to the bug in the Solaris
2.6 implementation of PAM, as described above. To date,
Hewlett-Packard does not have a patch to correct this problem.
EMSRV for Linux now supports authentication using PAM. This allows
both shadowed and non-shadowed passwords to be supported with one EMSRV
executable.
In addition, Red Hat Linux 6.2 supports MD5 passwords and EMSRV also
supports these via PAM
PAM must be correctly configured on a machine running EMSRV otherwise it
will not even be possible to shutdown EMSRV using EMADMIN. The PAM
configuration file must be copied to
/etc/pam.d/emsrv. A sample PAM configuration file is
included with this release (see /opt/IBMvast/5.5/samples/PAM).
EMSRV for Solaris now supports authentication using PAM. This allows
both shadowed and non-shadowed passwords to be supported with one EMSRV
executable.
There is a bug in the Solaris 2.6 implementation of PAM that
prevents EMSRV from working correctly. The patch 106257-05 must
be applied when using EMSRV with Solaris 2.6. The patch is
available at:
http://sunsolve.sun.com/pub-cgi/retrieve.pl?doc=fpatches%F106257&zone_32=PAM
The specific bug that this patch fixes is:
The patch is not required for Solaris 7.0.
PAM must be correctly configured on a machine running EMSRV otherwise it
will not even be possible to shutdown EMSRV using EMADMIN. The
/etc/pam.conf file is included with this release (see
/opt/IBMvast/5.5/samples/PAM).
Root access on UNIX platforms is required to authenticate users.
EMSRV does NOT need to be started by the root user to accomplish this.
Doing so would compromise security as EMSRV would then have complete access to
all filesystems.
Instead, you should change the owner of the EMSRV executable to
'root' and set the SUID bit of the executable. This can be
accomplished as follows:
when EMSRV attempts to authenticate a user, it will temporarily change the
authority of the running EMSRV process to be the authority of the owner of the
executable. Once authentication is complete, the authority of the
running EMSRV process will be changed back to that of the user that started
EMSRV. This happens on a per-process (per-client) basis so while a
client is being authenticated, only the process serving that client has
temporary root access.
Root access for authentication is required regardless of how EMSRV actually
implements authentication. Interfaces such as PAM only provide a common
API to permit applications to support multiple authentication methods,
configuration specific to each method of authentication must still be
correct. Account names authenticated by EMSRV for Windows NT/2000 can come from two
sources -- the name of the EMSRV user and the network names for users
managed in a repository. As of this release, an account name may be in
one of three formats:
Windows NT 4.0 and Windows 2000 non-domain controllers support
simple names and SAM-compatible names. Windows 2000 domain controller
support all three formats. Previous releases of EMSRV controllers
support all three formats. Previous releases of EMSRV for Windows NT
only supported simple names. The new formats allow authentication
between domains as well as in an Active Directory.
Windows NT and Windows 2000 supports installable authentication and
security packages, allowing the system to be extended with new forms of
authentication and security. EMSRV for Windows NT/2000 only supports
the default packages supplied with Windows NT and Windows 2000-namely
the MSV1_0 and Kerberos authentication packages and the NTLM (NT LAN Manager)
and Kerberos security packages.
EMSRV for Windows NT/2000 uses NTLM (NT Lan Manager) authentication on
Windows NT 4.0 and Windows 2000 non-domain controllers. User
records in these systems are stored in a SAM (Security Accounts Manager)
database.
To authenticate a user, EMSRV must first find the name of the domain with
the SAM database that contains the user to be authenticated. The term
domain applies equally to non-domain controllers because every SAM database
contains a built-in domain known as 'BUILTIN' as well as for
non-domain controllers, a domain with the same name as the machine or for
domain controllers, the controlled domain.
If a SAM-compatible name (specifying a domain) is supplied, then the domain
is already known. If a simple name is provided then the following are
checked to find the user:
Once the domain is known, an attempt is made to authenticate the user in
that domain.
If the domain name matches the name of the SAM database on the local
machine then the authentication is processed on that machine. The name
of the SAM database on a Windows NT Workstation that is a member of a domain,
is considered to be the name of that Windows NT machine. The name of
the SAM database on a Windows NT Advanced Server is the name of the
domain. If a Windows NT machine is not a member of a domain then
authentication is processed locally.
If the domain specified is trusted by the domain of the machine running
EMSRV, the authentication request is passed through to the trusted
domain. On a Windows NT workstation, the request is always passed
through to the primary domain controller of the workstation, allowing the
primary domain controller to determine if the specified domain is
trusted.
If the domain name specified is not trusted by the domain of the machine
running EMSRV, the authentication request is processed on that machine as if
the domain name specified were that domain (or computer) name. In other
words, the domain name is ignored. The system does not differentiate
between a nonexistent domain or an untrusted domain.
An example illustrates how cross-domain authentication can be setup:
There are two domains: KIRA and CHIEF. The domain controller
for the KIRA domain is NT4PDC. The domain controller for the CHIEF
domain is NT4PDC2. A trust relationship is setup so that CHIEF is a
trusted domain of KIRA (and hence KIRA is a trusting domain of CHIEF).
The trust relationship is one-way such that KIRA is not a trusted domain of
CHIEF.
EMSRV is setup to run on KIRA\NT4PDC. Users in both
domains can be authenticated. Account names may be specified using a
simple name in which case EMSRV will locate the domain containing the user, or
the domain may be specified using a SAM-compatible name such as
CHIEF\ADRIAN.
EMSRV is setup to run on CHIEF\NT4PDC2. Only users in the CHIEF
domain can be authenticated because KIRA is not a trusted domain of the CHIEF
domain.
EMSRV for Windows NT/2000 uses Kerberos authentication on Windows
2000. User records for Windows 2000 domain controllers are stored in an
Active Directory instead of a SAM database. The KD (Key Distribution
Center) service must be running to use Keberos authentication.
If a simple name is supplied, then the procedure for locating the user is
the same as that for Windows NT 4.0 and Windows 2000 non-domain
controllers. The one difference is that in addition to checking the
following:
every domain in the forest for the machine running EMSRV, is also
checked. This makes sense since a forest is a collection of Active
Directory trees connected by two-way transitive trust relationships.
A SAM-compatible name will be authenticated with the domain that the name
specifies. A User Principal Name will be authenticated with Active
Directory Services.
The implementation of Kerberos authentication in Windows 2000 is already
well-documented elsewhere and does not need to be repeated here. In
summary:
The NTLM protocol requires that the server must contact a domain
controller. When Kerberos is used, the server does not have to contact
the domain controller. A client gets a ticket for a server by
requesting one from a domain controller in the server account domain; the
server validates the ticket without consulting any other machine.
An example illustrates how Active Directory authentication can be
setup:
There are three Active Directory domains - ibm, ral.ibm, and
engineering.ral.ibm. The
engineering.ral.ibm domain is a child of the ral.ibm
domain and the ral.ibm domain is a child of the ibm domain. Each
parent-child relationship automatically creates a two-way transitive trust
relationship. As a result, since ral.ibm trusts
engineering.ral.ibm and ibm trusts ral.ibm, ibm trusts
engineering.ral.ibm. The three domains form a
tree.
In addition there is another Active Directory domain - bedrock, which forms
a tree of one domain. The ibm tree and the bedrock tree together form a
forest - they share a common schema, configuration, global catalog, and are
linked with two-way transitive trusts at the tree roots.
Finally there is an NT 4.0 domain - KIRA. A one-way trust
relationship is setup so that ibm trusts KIRA.
If EMSRV is run on the domain controller for the ibm domain, users from the
following domains can be authenticated:
Simple names for users in any of those domains will cause a search to be
initiated to find the domain containing the user. Alternatively, names
may be specified in any one of the other two formats previously
described.
A number of advanced user rights are required for authentication to work
correctly. Authentication is required even if EMSRV is not started with
the -rn option since EMSRV authenticates the EMSRV account when it is started
and stopped.
As detailed in the EMSRV documentation, Advanced user rights are set in the
User Manager for Windows NT 4.0 and the Local Security Policy for
Windows 2000 Professional. For Windows 2000 Server, it may be necessary
to also set the rights in the Domain Controller Security Policy and the Domain
Security Policy so that the Effective Policy Setting for each right is correct
in the Local Security Policy. Windows 2000 Advanced Server does not
have a Local Security Policy. Instead, the right should be set in the
Domain Controller Security Policy and the Domain Security Policy as
necessary.
Each of the advanced user rights required for correct EMSRV operation are
detailed below
In previous releases of EMSRV, two versions of the EMSRV for NetWare NLM
were supplied - one that used bindery authentication and one that used NDS
authentication. Bindery authentication is no longer supported.
This release includes one NLM that supports NetWare 4.2 and
5.1. EMSRV no longer supports versions 3.x of
NetWare.
Account names authenticated by EMSRV for NetWare can come from two sources
- the name of the EMSRV user and the network names for users managed in a
repository. Account names can be simple or distinguished. Both
forms can also be typeful or typeless. Some examples are provided
below:
Names are always authenticated in the context of the NDS context that is
specified when EMSRV is started (the context is appended to the account
name). Absolute names (those preceded with a period) are authenticated
in the [Root] context (any context specified when EMSRV was started, is
ignored). For each trailing period in a name, one component of the
context is removed before being appended to the name. This allows names
to be resolved in containers that are higher in an NDS tree than the specified
context. Some examples:
By using a distinguished name, it is possible to authenticate users in
different containers. The most common case for this may be if the
account names for users are located in one container but the EMSRV user is
located in another. For example, if Netware accounts corresponding to
network names of users in a repository exist in the container
'engineering.ral.IBM' but the EMRSV user exists in the
container 'IBM', the following command could be used to load
EMSRV:
Alternatively, the following command would also accomplish the same
result:
Authentication on UNIX Platforms
PAM
Authentication on AIX platform
Authentication on HP-UX platforms
Authentication on Linux platforms
Authentication on Solaris platforms
4092227 pam_conv appdata_ptr member is not passed thru to conv() function as documented
Usage of Root Access for Authentication
chown root emsrv
chmod u+s emsrv
Authentication on Windows platforms
Simple name
adrian
Windows NT 4.0 SAM-compatible name
engineering\adrian
user principal name
adrian@ral.ibm.com
Authentication Procedure using Windows NT and Windows 2000 Non-Domain Controllers
Authentication Procedure Using Windows 2000 Domain Controllers
ibm
ral.ibm
engineering.ral.ibm
bedrock
KIRA
Advanced User Rights Required for Authentication
Authentication on NetWare platforms
Simple typeless name
adrian
Simple typeful name
CN=adrian
Distinguished typeless name
adrian.engineering.ral.IBM
Distinguished typeful name
CN=adrian.OU=engineering.OU=ral.O=IBM
Context engineering.ral.IBM
Name adrian
Resulting name adrian.engineering.ral.IBM
Context engineering.ral.IBM
Name .admin.IBM
Resulting name .admin.IBM
Context engineering.ral.IBM
Name kathy.support.phx..
Name kathy.support.phx.IBM
load emsrv -u .EMSRV.IBM -p test - W sys:emsrv -rn -SC engineering.ral.IBM
load emsrv -u EMSRV.IBM.. -p test - W sys:emsrv -rn -SC engineering.ral.IBM
Install your VisualAge Smalltalk Manager Library on a file systems local to the computer that is running EMSRV.
On Windows and OS/2, do not use a mapped network drive.
On UNIX, do not use a remote NFS file system.
EMSRV has the file access rights of the EMSRV account for PC platforms or the account that starts EMSRV under UNIX. This means that the EMSRV account must have access rights to all directories and files that VisualAge users require. To ensure the integrity of the library file manager.dat, the access rights for this file may be restricted to the EMSRV account.
All files created by EMSRV are owned by the EMSRV account.
The EMADMIN command-line utility helps you manage and communicate with a repository server (EMSRV) from any network attached workstation where emadmin.exe is installed.
The EMADMIN utility consists of the
following commands:
| Command | Description |
|---|---|
| copy | Copies a VisualAge library on the server. |
| help | Displays the valid commands and options. |
| list | Displays the current EMSRV connection list or information about a specific connection. |
| opts | Displays the current EMSRV options. |
| stat | Displays EMSRV statistics. |
| stop | Shuts down EMSRV remotely or kills an active connection. |
EMADMIN uses the following syntax:
EMADMIN [command] [command modifier] [option]
| Syntax | Description |
|---|---|
| [command] | The EMADMIN command you are issuing. |
| [command modifier] | The specific modifiers for that command. These are described in the documentation of each command. |
| [option] | EMADMIN has one option, the port number, -P<port number>. This parameter specifies the port that EMSRV is using instead of the default. The default port number is 4800. This option is available for all EMSRV commands. |
| [<host>] | specifies the hostname or IP address of the server, where EMSRV is running. |
Statistics gathered by EMADMIN can either be displayed on the screen or redirected to a file.
For example, to send the list of current connections to EMSRV running on an IP address 137.65.2.11 to the screen, enter:
EMADMIN list 137.65.2.11
To send the list of current connections to EMSRV running on the local machine to the file clist.txt, enter:
EMADMIN list > clist.txt
The copy command allows you to copy one repository, the source, to another repository, the target. The target repository can be on the same EMSRV server as the source, or on a different EMSRV server that is on the same network.
The copy command locks the library to ensure that the library cannot be changed while it is being copied.
To use the copy command, the following conditions must exist:
The syntax for the copy command is:
EMADMIN copy [-o] [-p<password>][-q][ -P<port number> ] <source> <dest>
| Parameter | Description |
|---|---|
| <source> | A valid VisualAge library file; the source file will be locked. |
| <dest> | File specification must be accessible to the EMSRV user account. A
VisualAge file specification has the following format:
<ip_address>:<file name> <ip_address> is optional and specifies the host that EMSRV is running on. It can be either the file server IP host name or its Internet address. If a host name is not provided, localhost is used. <file name> is required and is the file specification. |
| Modifier | Description |
|---|---|
| -o | The copy command default behavior does not overwrite an existing file. Normally, you are prompted for overwrite permission. The -o option specifies that the destination file may be overwritten without prompting. |
| -p | This specifies the password to use when the copy command is validating access to the source database. The password cannot contain spaces. |
| -q | By default, the copy command prints the number of bytes transferred during the copy operation. The -q option indicates "quiet operation" and the transfer count is not printed. When this option is enabled, you will not be prompted about potential problems from low disk space. |
| -P <port number> | This is an optional parameter that specifies the port that EMSRV is using . The default numbers is 4800. |
For example, to copy a library file to a backup file, enter the following command:
emadmin copy -o -p secret -q 15.1.33.20:manager.dat 15.1.33.20:test.dat
This example copies (in quiet mode) manager.dat to test.dat in the working directory, overwriting test.dat if it exists and using the password "secret" to access the source library.
The list command lists current connections for to a repository server. This command sends a message to the host running EMSRV and requests the list of connections. Information about connection statistics and active locks can be obtained using the list command modifiers.
The syntax for the list command is:
EMADMIN list [command modifiers] [<host>[-P<port number>]]
The list command has the following modifiers:
| Modifier | Description |
|---|---|
| -s[<connection number>] | Displays the statistics for the connection specified by <connection number>. |
| -l[<connection number>] | Displays the active locks for the connection specified by <connection number>. |
| <host> | Specifies the host name or IP address of the server where EMSRV is running. If you don't specify a host, the default is the name of the host from which you are issuing the emadmin command. |
| -P <port number> | This is an optional parameter that specifies the port that EMSRV is using . The default numbers is 4800. |
For example:
emadmin list emsrv.ibm.com
Running this command produces output such as the following:
==============================================================================
EMSRV 7.0 for Windows NT/2000 Aug 1 2000 22:28:51 (EST)
Operating system: Windows NT Workstation 4.0.1381 Service Pack 4 (1 Processor -
255 MB Memory)
Code page (ANSI): 1252
Active Last
ID IP Address Locks Request Socket File
------------------------------------------------------------------------------
0 9.25.62.92 0 09:58:23 808 e:\emsrv\vast\va000816_dev.dat
1 9.25.62.110 0 17:09:52 456 e:\emsrv\vast\va000816_dev.dat
3 9.25.62.108 0 16:49:02 1668 e:\emsrv\vast\va000816_dev.dat
8 9.25.62.111 0 14:13:10 1196 e:\emsrv\vast\va000816_dev.dat
------------------------------------------------------------------------------
There are 4 active connections.
==============================================================================
The opts command enables you to display the current options for a repository server and change the logging level for the repository server.
The syntax for the opts command is:
emadmin opts <host> [-s<level>]
| Parameter | Description |
|---|---|
| <host> | Specifies the host name or IP address of the server where EMSRV is running. If you don't specify a host, the default is the name of the host from which you are issuing the emadmin command. |
| -s<level> | Specifies a new logging level for EMSRV. This command allows you
to change the current logging level without having to access the machine where
EMSRV is running. You can specify the following logging levels:
|
| -P <port number> | This is an optional parameter that specifies the port that EMSRV is using . The default numbers is 4800. |
For example:
emadmin opts emsrv.ibm.com
Running this command produces output such as the following:
============================================================================== EMSRV 7.0 for Windows NT/2000 Aug 1 2000 22:28:51 (EST) Operating system: Windows NT Workstation 4.0.1381 Service Pack 4 (1 Processor - 255 MB Memory) Code page (ANSI): 1252 Running as a service: Yes Maximum number of concurrent connections: 256 Working directory: d:\bin\emsrv\data Authentication: Disabled Logging level: Error Log file name: emsrv.log Allow connection to truncate repositories: No Track EMSRV statistics: Yes Track process file locking statistics: No Process activity timeout value: 360 sec Sleep on lock value: 1000 ms Free disk space warning threshold: 10000 KB Restrict repositories to local filesystems: Yes ==============================================================================
The stat command displays the statistics for operations completed since the repository server was started. This command also tells you what the current EMSRV working directory is.
The stat command sends a message to a host running EMSRV and requests a copy of the latest statistics. This command provides information such as numbers of file opens, closes, and writes.
The syntax for the stat command is:
EMADMIN stat [ <host> ]<-P<port number>]
| Parameter | Description |
|---|---|
| <host> | Specifies the host name or IP address of the server where EMSRV is running. If you don't specify a host, the default is the name of the host from which you are issuing the emadmin command. |
| -P <port number> | This is an optional parameter that specifies the port that EMSRV is using . The default numbers is 4800. |
For example:
EMADMIN stat emsrv.ibm.com
Running this command produces output such as the following:
============================================================================== EMSRV 7.0 for Windows NT/2000 Aug 1 2000 22:28:51 (EST) Operating system: Windows NT Workstation 4.0.1381 Service Pack 4 (1 Processor - 255 MB Memory) Code page (ANSI): 1252 Total Connects: 398 Total Disconnects: 393 Total Opens: 1720 Total Closes: 1696 Active Locks 0 Unexpected Connection Closes: 20 Total Locks: 675831 Total Unlocks: 675830 Total Reads: 3436990 Total Writes: 636179 Total Reads Failed On Lock: 0 Total Locks Failed On Lock: 0 Times Lock Limit Hit: 0 Total Requests Serviced: 6009719 Requests in last interval: 0 Largest Packet Sent: 32780 Largest Packet Received: 32784 Working Directory : d:\bin\emsrv\data Server Has Been Alive For: 17 Days 0 Hours 45 Minutes 18 Seconds ==============================================================================
The stop command shuts down EMSRV remotely or closes a client connection to EMSRV. When you use this operation to shut down EMSRV, you are prompted for the EMSRV account password. The password characters are not displayed on the screen. EMSRV can be shut down only if you have entered the correct password. The stop command can also be used to terminate a connection that can no longer communicate with the client. Use the list command to obtain the list of connections and their respective connection numbers that can be closed.
The stop -k <connection number> command is used to close a client connection to EMSRV.
The syntax for the stop command is:
emadmin stop <server_address> [ -k <connection_number> ] [ <host> ]
| Parameter | Description |
|---|---|
| <server_address> | This optional parameter specifies the host that EMSRV is running on. The parameter can be either the server host name or its Internet address. If a host name is not provided, localhost is used. |
| -k <connection_number> | This required parameter is the unique connection number of the connection to be terminated. |
| <host> | Specifies the host name or IP address of the server where EMSRV is running. If you don't specify a host, the default is the name of the host from which you are issuing the emadmin command. |
If you are going to use VisualAge Smalltalk for team development, linking several application programmers to one central code repository, the Manager Library, you will need to use EMSRV. The EMSRV code is installed when you install the Manager Library.
Before you start EMSRV for Windows NT/2000, perform the following steps:
EMSRV uses an existing Windows NT/2000 account to provide file access restrictions. The Windows NT/2000 account name used by EMSRV is referred to as the EMSRV account name, and the password for that account is referred to as the EMSRV account password. Both the Windows NT/2000 account from which EMSRV is started (that is, if EMSRV is not started as a service) and the EMSRV account must be granted the advanced user right Act as part of the operating system and be a member of the Administrators group.
The following steps cover how to set and activate this right for Windows NT:
Use the following directions to set and activate this right for Windows 2000:
For Windows 2000 Server, the Local Security Policy may be overridden by the Domain Controller Security Policy or the Domain Security Policy. User rights for the domain controller and/or domain may need to be set in order for the Effective Policy Setting in the Local Security Policy to appear checked.
For Windows 2000 Advanced Server, there is no Local Security Policy. Assign the right for the Domain Controller Security Policyand Domain Security Policy as necessary.
Authentication for the EMSRV account is slightly different when
authenticating clients. In each case, additional user rights ay be
required for successful operation.
Perform the following steps to start EMSRV for Windows NT/2000 from the command line:
For example, at the NT/2000 command line enter:
emsrv -u EMSRVUSER -p swordfish -W d:\path -w
This command does the following:
The following steps cover how to install EMSRV as a Windows NT/2000 service. See Troubleshooting EMSRV as a Windows NT/2000 service for a listing of common problems and solutions when running EMSRV as a Windows NT/2000 service.
Ensure that -install is the first parameter. This installs EMSRV as a service in the registry and copies the necessary DLLs to the system directory. If there is an older version of EMSRV already installed, it removes the older version and installs the new version.
To stop the service, enter sc stop EMSRV.
To remove the EMSRV Service from the registry, enter EMSRV -remove at a DOS command prompt. Alternatively, you can remove it by entering sc delete EMSRV.
The -remove option will stop the service if it is running as well as delete it from the registry.
Following are some guidelines for running EMSRV as a Windows NT/2000 service:
This section describes common problems when running EMSRV as a Windows
NT/2000 service and their solutions.
| Problem | Solution |
|---|---|
| The error message An internal Windows NT error has occurred appears at startup | Open the Services control panel. Verify that the startup parameters are entered correctly and the user name is a valid user on the server. The -u option is always needed to start the server. |
| Normal EMSRV (not a service) hangs on startup | EMSRV must be run in the directory of the executable. It will pause for about 1 minute if it is run with no arguments from a different directory. |
| The error message The specific service is disabled and cannot be started appears at startup | From the Control Panel, select Services and then the HW Profiles button. Select the Original Configuration. If its status is disabled, enable it by selecting the Enable button. |
| The start button is disabled | The service could already be running on the local machine. Otherwise the service could be disabled. Select EMSRV Service in the Services control panel. Select Startup to open the Service window. Select Automatic or Manual for Startup Type. |
| The error message The service did not start due to a logon failure appears at startup | An invalid password was entered in the Service window of the Services control panel, which you access by selecting Startup. Open the Service window and change the password or log on as the System Account. |
| The error message The process terminated unexpectedly appears at startup | EMSRV could already be running in normal mode (that is, not as a service) on the local machine. This instance must be stopped for EMSRV to run as a service. |
Before you start EMSRV for OS/2, perform the following steps:
EMSRV for OS/2 does not require a logon account to start. A password may be provided to protect against unauthorized shutdown.
Perform the following steps to start EMSRV for OS/2:
For example, at the OS/2 command line enter the following:
emsrv -p swordfish -W c:\manager -lc
This command starts EMSRV with the working directory c:\manager and logs messages to the console.
This section describes how to set up, start, and use EMSRV for NetWare.
EMSRV for NetWare uses one thread per client connection and therefore scales more readily to support a greater number of connections than EMSRV for OS/2 or any of the EMSRV UNIX implementations, which use one process per client connection.
Paths to libraries accessed via EMSRV for NetWare must be specified as a NetWare path, relative to the EMSRV working directory (specified at the command line) and may include a NetWare volume name such as SYS. It is not possible to access a library residing on a remote server. Each NetWare server that has volumes containing libraries to be accessed must be running a copy of EMSRV for NetWare.
When using EMSRV for Netware, long filenames may only be created and viewed on NetWare volumes to which the LONG or OS/2 namespace has been added.
It is recommended that the NetWare Minimum Patch List be applied to
the server running EMSRV for NetWare. The various files may be obtained
from Novell's website at:
http://support.novell.com/search/patlst.htm
Before you load the EMSRV NLM, perform the following steps:
The EMSRV NLM logs on to the NetWare file server using an existing NetWare account and password to provide file access restrictions. The NetWare account name used by EMSRV is referred to as the EMSRV account name, and the password for that account is referred to as the EMSRV account password.
When you load the EMSRV NLM, you must supply it with the EMSRV account name, the EMSRV account password, and a working directory. You can supply this information using command-line parameters. If you do not supply this information, the NLM prompts you as it loads.
Perform the following steps to start EMSRV NLM:
For example, at the file server console enter:
load emsrv -u EMSRVUSER -p swordfish -W volname:\path -sc context
This command does the following:
This section describes ways to operate EMSRV for NetWare.
EMSRV creates two console screens:
Context-sensitive help may be viewed at any time by pressing F1.
Through the Menu Screen you can perform the following operations:
When you select Change Settings, a form is displayed that you can view and edit. To exit the form and save the changes (which implements them), press Esc.
The following table describes each form field and lists the corresponding
startup option, if one exists, and the default value.
| Field | Description | Startup option (default) |
| Maximum Number of Connections | Displays the maximum number of connections allowed by EMSRV. | -w (default: 256) |
| Logging Level | Displays the current reporting level. To change the reporting level, press Enter to access a pop-up menu. | -s0 (logs all operations)
-s1(logs warning and error messages) -s2 (default: logs only error messages) |
| Log to a File | Specifies whether EMSRV logs to a file. | -lf <file name> |
| Log File Name | Specifies the log file to which EMSRV writes. | -lf <file name> |
| Allow Libraries to be Truncated | Specifies whether users are allowed to truncate existing libraries. | -t (default: yes) |
| Client Password Verification | Specifies whether client password verification is disabled, whether native NetWare passwords are used, and whether the passwd.dat file is used. To change the style of password verification, press Enter to access a pop-up menu. | -rn (rejects users who do not supply a valid NetWare user name
and password)
-rd (default: disables password checking for clients) -rp (rejects users who are not in the passwd.dat file) |
| Statistics Recorded per Screen Update | Specifies the number of statistics that must change before EMSRV updates its statistics screen. The higher you set this number, the better EMSRV performance you will get. | (default: 1000) |
Select View Connections to display a list of client connections. You can scroll through the list to select a specific connection. After selecting a connection:
To display EMSRV statistics, select EMSRV Statistics from the Menu Screen.
Select View Message Screen from the Menu Screen to display the Message Screen. To return to the Menu Screen, press Esc.
Select EMSRV Statistics from the Menu Screen to display EMSRV statistics that have been accumulated since the EMSRV NLM was started.
You typically display EMSRV statistics after displaying connection statistics using View Connection List.
To force a screen update, select EMSRV Statistics if the EMSRV statistics are currently displayed.
To change the reporting level from the NetWare console while EMSRV is running:
When debugging an EMSRV problem, it is often useful to watch the write operations to the Message Screen as they occur. To do this, switch to the Message Screen after setting the reporting level.
You cannot unload EMSRV for NetWare using the unload command at the file server console. You can unload it only from the Menu Screen or by running EMADMIN. (For information on using EMADMIN, see The EMADMIN utility.)
Do not unload EMSRV for NetWare if library transactions are in progress. If you do, the library may be left in an inconsistent state.
The following steps describe how to safely unload EMSRV:
EMSRV no longer supports NetWare 4.11 or NetWare 5.0, but EMSRV can be run on those platforms if additional steps are taken. CLIBAUX.NLM must be loaded before the EMSRV NLM is loaded. CLIBAUX.NLM is included with Novell's NetWare 4.11/4.2 Support Pack 8a, but is also available separately from Novell in the file CLIBAUX1.EXE, which can be found at the following location:
http://support.novell.com/cgi-bin/search/download?/pub/updates/nw/nw42/clibaux1.exe
In previous releases of EMSRV for NetWare, two additional files - EMSRV.HLP and EMSRV.MSG were required along with the NLM. These files are no longer needed as they have been bound into the NLM.
Before you start EMSRV for UNIX, perform the following steps:
By default, EMSRV on UNIX permits access to libraries only on certain known local file systems. This is done to avoid corruptions which can occur when libraries are stored on networked file systems. If you intend to locate libraries on a file system that is not recognized by default, you must specify an -xd option for that file system. If you do not, your clients will receive a "File resides on an unsupported device" error when they try to open a library.
emdevnum is a utility which retrieves the major device ID for the file system of a specified file. The device number reported may then be used with the emsrv -xd startup option.
EMSRV does not have to be running in order to use emdevnum.
Syntax
emdevnum <file or directory name>
Example
emdevnum /opt/IBMvast/5.5/manager/mgr55.dat emdevnum /opt/IBMvast/5.5/manager
A typical response might be:
The device number is 21
WARNING: The -xd option can bypass checking for a remote file system. If a library is located on a remote file system (or even a local file system mounted using a remote protocol), the library can become corrupted. Make sure that devices specific with -xd are local to the machine running EMSRV and are not from mounted remote file systems like NFS.
Accessing libraries on remotely-mounted volumes such as those hosted by NFS may result in library corruptions. This is due to the fact that some remote file system software cannot guarantee the integrity of a file when multiple clients are updating it. Although EMSRV uses locks to serialize access to regions of a library, some locking implementations of NFS, for example, use UDP, which does not guarantee delivery or the sequence of transmissions.
On many platforms, NFS file systems return an unusual value (such as 0 or 65535) to emdevnum. However, even if the major device ID appears to be a reasonable value, check to make sure that device is local to the machine running EMSRV before specifying it with the -xd parameter.
On UNIX platforms, the EMSRV process will have the file access permissions of the UNIX account that starts EMSRV. The UNIX account name that is used to start EMSRV is referred to as the EMSRV account name, and the password for that account is referred to as the EMSRV account password.
Perform the following steps to start EMSRV for UNIX:
For example, at a command line, enter either: emsrv.shadow -w -xd21 -xd24 -lc -lflogfile or emsrv -w -xd21 -xd24 -lc -lflogfile.
The command does the following:
| Platform | Operating Systems Included |
| Netware | Netware |
| OS/2 | OS/2 |
| UNIX | HP, Sun, AIX, Linux |
| Win | Windows 2000, Windows NT |
| All Platforms | AIX, HP, Netware, Linux, OS/2, Sun, Windows 2000, Windows NT |
The following table lists and describes EMSRV startup parameters.
| Parameter | Platform | Description |
| -A<0,1> | All platforms | The file system requires read locks. The default setting is 0, which indicates the file system does not need read locks. |
| -a<seconds> | UNIX | Sets the number of seconds before a connection is deemed inactive. The default is 360 seconds. |
| -b<Kilobytes> | All platforms | Sets the low-volume threshold warning in kilobytes. The default is 10,000 kilobytes. If the available disk space is less than the low-volume threshold, EMSRV will log warning messages to the log file. |
| -f | UNIX | Sets EMSRV to run in the foreground. |
| -h | All platforms | Displays the help text that lists the valid options. |
| -i<q,t> | UNIX | Ignores signals. <q> = ignore SIGQUIT; <t> = ignore SIGTERM. By default, either of these signals cause EMSRV to terminate. |
| -install | Win | Installs EMSRV as a service. |
| -lc | OS/2, Win, NetWare | Logs messages to the console. By default, messages are not written to the console. |
| -lf<name> | OS/2, Win, NetWare | Writes the log to file <name>. By default, the log is written to emsrv.log. The file <name> must specify a valid path for which the EMSRV account has sufficient access rights. |
| -lp<seconds> | UNIX | Sets the maximum number of seconds to wait for a lock. The default is 15 seconds. |
| -ls | UNIX | Logs messages to stdout instead of a log file. EMSRV must be run in the foreground using the -f option if -ls is used. |
| -lt<seconds> | UNIX | Sets the maximum number of seconds to hold a lock. |
| -M<number of connections> | All platforms | Specifies the maximum number of connections that can be established with
EMSRV. The default is 256.
To start EMSRV with a maximum of 80 client connections, use the following parameter: load EMSRV -M80 |
| -n | UNIX | Turns off statistics gathering. |
| -P<port number> | All platforms | Specifies the port number that the EMSRV process uses. The default
is 4800.
To start EMSRV using port number 4899, use the following parameter: load EMSRV -P4899 If you need to change the port number on the client and do not know how, contact customer support. |
| -p <password> | OS/2, Win, NetWare | Specifies the password for the EMSRV user account and restricts library
file access. This password is used for EMADMIN functions, such as
shutting down EMSRV remotely. Refer to the section "The EMADMIN
utility" for information on EMADMIN functions.
For NetWare, you must specify -p without the password parameter if the EMSRV account has no password. |
| -R<0,1> | All platforms | The file system releases locks on file close. The default setting is 1, which indicates the file system releases locks when files close. |
| -r | UNIX | Rejects users who are not in the passwd.dat file. |
| -rd | OS/2, Win | Disables password checking for clients. This is the default setting. |
| -remove | Win | Removes the EMSRV service from the Registry. |
| -rn | Win, NetWare | Rejects users who do not supply a valid EMSRV user name and password. The default grants access to users without an EMSRV user name and password. |
| -rp | OS/2, Win, NetWare | Rejects users who are not in the passwd.dat file. The default grants access to users who are not in the password file. |
| -s<0, 1, 2> | All platforms | Sets the reporting level to the specified severity level (0, 1, or 2). See the section following, "EMSRV messages and reporting," for a description of severity levels. The default is 2 (log error messages only). |
| -sc | NetWare | Sets the NDS context for EMSRV to <context>. Consult your NetWare documentation for information on setting NDS contexts. |
| -t | All platforms | Protects existing files from truncation. By default, files are created over existing ones; that is, the existing file is truncated to 0 length. |
| -u <user name> | Win, NetWare | Specifies the EMSRV account name to be used. |
| -v | UNIX | Verifies password using system authentication. |
| -W <path> | OS/2, Win, NetWare | Specifies the EMSRV working directory. The directory <path> must be a valid path for which the EMSRV account has sufficient access rights to read, write, or both. |
| -w | All platforms | Specifies that EMSRV should track locks for each connection. |
| -xd <devnum> | UNIX | This parameter allows EMSRV to open libraries on devices other than the
default hard drive. A maximum of 15 devices may be specified. If
you intend to locate libraries on a hard drive other than the boot drive, you
must specify an -xd option for each other hard drive. If you
do not, your client will generate the error "File resides on an unsupported
device".
Warning: The -xd option can bypass checking for a remote file system. If a library is located on a remote file system (or even a local file system mounted using a remote protocol), the library can become corrupted. Make sure that devices specified with -xd are local to the machine running EMSRV and are not from mounted remote file systems like NFS. |
EMSRV contains comprehensive diagnostics. Based on the specified reporting severity level and whether file logging is enabled, statistics and diagnostic information are logged to the emsrv.log file and displayed on the console (or on the EMSRV for NetWare Message Screen). All messages with a severity level lower than the current level are suppressed. You can set the level when you start EMSRV, and you can change it dynamically, using the EMADMIN utility. The reporting levels are as follows:
There are three categories of EMSRV messages:
During normal operation, you should set the reporting level to "Errors" (reporting-level 2), because performance is affected when large amounts of information are written to the screen or log file. Set the reporting level to "Information" only when you are trying to diagnose a problem.