Chapter 8
Administration Server Command-Line Tools
The command-line tools (utilities) described in this chapter come with iPlanet Administration Server. You can use these utilities to configure an instance of Administration Server without launching iPlanet Console:
This chapter tells you how to use the command-line tools.
admconfig
The admconfig utility allows you to configure an instance of Administration Server using the command line instead of using the iPlanet Console graphical interface. Use admconfig to modify network, access, encryption, or directory settings. The utility is stored at serverRoot/bin/admin.
Syntax
admconfig [options] task [args] [task2] [args] [task3] [args] ...
The options that you can use with admconfig are described in the section that follows. The tasks that you can perform with admconfig, as well as the arguments for those tasks, are described in "Tasks and Their Arguments."
Options
An option is a general setting that affects how admconfig runs. You can specify an option using a complete command such as -user or an abbreviated command such as -u. When specifying a command, make sure to use enough characters to differentiate it from other commands.
Option commands are not case sensitive. For example, both -USER and -User are accepted as the -user command. You can use multiple option commands with the same invocation of admconfig. For example, the following option commands specify that admconfig should establish an encrypted connection with eastcoast.siroe.com on port 904.
-enc -ser eastcoast.siroe.com:904
Table 8-1 Options You Can Use With admconfig
|
Commands for Options
|
What the Command Does
|
|
-con[tinueOnError]
|
Finishes any remaining tasks (that have been specified on the command line) when an error occurs. (Default behavior when any task fails is to quit without running the remaining tasks.)
|
|
-enc[ryption]
|
Uses encrypted HTTP (HTTPS) to connect to the server. (The default protocol is HTTP.)
|
|
-h[elp] [task]
|
Displays general usage information. Include a task name for usage information specific to that task.
|
|
-i[nputFile] filename
|
Reads options and tasks from the specified file. You can specify additional options on the command line. If an option is present on the command line and in the specified file, the command-line settings are used. If the -inputFile option is present in the specified file, it is ignored to prevent admconfig from reading multiple sets of options.
|
|
-ser[ver] [host]:port
|
Connects to the server on the specified host and port. If a host isn't specified, the local host is used. The server port number (preceded by the colon) is required.
|
|
-u[ser] [uid]:[pwd]
|
Connects to the server using the specified user name and password. If a user name is not specified, you will be prompted for the current user's password.
The password appears onscreen when it is typed, so if security is a concern, use the -inputFile option and list the user name and password in a file with suitable permissions. Note that if the -user option is specified, then, at a minimum, the colon must be specified. If the -user option is not specified, then the user is prompted for both the user name and password.
|
|
-verb[ose] [0-9]
|
Sets the level of screen output (9=full output, 0=no output).The default level is 9.
|
|
-vers[ion]
|
Displays the version and copyright information.
|
Tasks and Their Arguments
A task specifies an operation that admconfig should perform. Some tasks take arguments, commands that provide information necessary to complete an operation.
You can specify a task using a complete command such as -restart or an abbreviated command such as -r. When specifying a task command, make sure to use enough characters to differentiate it from other commands. The task commands are not case sensitive. Both -RESTART and -Restart are accepted as the -restart task.
You can run multiple tasks with the same invocation of admconfig. If you use the -i[nputFile] option command to specify an input file, admconfig runs the tasks contained in that file first. The admconfig utility executes tasks in the order that they are specified in the input file and then in the order specified on the command line.
Table 8-2 Tasks You Can Perform With admconfig
|
Commands for Tasks
|
What the Command Does
|
|
-countA[ccessLogEntries]
|
Counts the number of entries in the access log file. Run this task before -viewAccesslogEntries to determine the number of entries in the access log.
|
|
-viewA[cessLogEntries]
|
Lets you view the specified entries in the error log file.
Syntax
admconfig [options] -viewAcessLogEntries \"start stop\"
Required Arguments
start The number of the first log entry to display.
stop The number of the last log entry to display.
On UNIX systems, the backslash character is required before the quotes surrounding the start and stop arguments. If the backslash is not provided, the shell will evaluate the quotes and pass the arguments without quotes to the command line. As a result, only start will be assigned as a parameter for -viewAcessLogEntries, causing the operation to fail.
|
|
-countE[rrorLogEntries]
|
Counts the number of entries in the error log file. Run this task prior to -viewErrorLogEntries to determine the number of entries in the error log.
|
|
-viewE[rrorLogEntries]
|
Lets you view the specified entries in the error log file.
Syntax
admconfig [options] -viewErrorLogEntries \"start stop\"
Required Arguments
start The number of the first log entry to display.
stop The number of the last log entry to display.
On UNIX systems, the backslash character is required before the quotes surrounding the start and stop arguments. If the backslash is not provided, the shell will evaluate the quotes and pass the arguments without quotes to the command line. As a result, only start will be assigned as a parameter for -viewErrorLogEntries, causing the operation to fail.
|
|
-enableD[SGWAccess]
|
Enables access to this instance of Administration Server from the Directory Server gateway.
|
|
-disableD[SGWAccess]
|
Disables access to this instance of Administration Server from the Directory Server gateway.
|
|
-getAc[cessLog]
|
Retrieves the path for the access log file for this instance of Administration Server.
|
|
-setAc[cessLog]
|
Specifies the path for the access log file for this instance of Administration Server.
Syntax
admconfig [options] -setAccessLog filename
Required Argument
filename Full path of the new server access log file.
|
|
-getAdd[resses]
|
Lets you view the IP addresses from which connections are allowed.
|
|
-setAdd[resses]
|
Specifies the IP addresses from which connections are allowed.
Syntax
admconfig [options] -setAddresses addresses
Required Argument
addresses New IP addresses and host names (separated by spaces) from which connections are allowed.
|
|
-getAdminUI[D]
|
Retrieves the Administration Server Administrator's user name.
|
|
-setAdminUI[D]
|
Specifies the Administration Server Administrator's user name.
Syntax
admconfig [options] -setAdminUID uid
Required Argument
uid The new Administration Server Administrator's user ID.
|
|
-setAdminP[wd]
|
Specifies the Administration Server Administrator's password.
Syntax
admconfig [options] -setAdminPwd password
Required Argument
password The new password for the Administration Server Administrator.
|
|
-getAdminUs[ers]
|
Retrieves the path of the adminusers file.
|
|
-setAdminUs[ers]
|
Specifies the path of the adminusers file.
Syntax
admconfig [options] -setAdminUsers adminusers
Required Argument
adminusers New path for the adminusers file.
|
|
-getCa[cheLifetime]
|
Displays the amount of time for which a user authentication is cached.
|
|
-setCa[cheLifetime]
|
Specifies the amount of time to cache a user authentication.
Syntax
admconfig [options] -setCacheLifetime msec
Required Argument
msec New cache lifetime in milleseconds.
|
|
-getCl[assname]
|
Retrieves the Java classname for this instance of Administration Server.
|
|
-setCl[assname]
|
Specifies the Java classname for this instance of Administration Server.
|
|
-getDe[faultAcceptLanguage]
|
Displays the default language for this instance of Administration Server.
|
|
-setDe[faultAcceptLanguage]
|
Specifies the default language for this instance of Administration Server.
Syntax
admconfig [options] -setDefaultAcceptLanguage language
Required Argument
language New default language. This is specified with an ISO 639 two letter code. For example, English is en.
|
|
-getDS[Config]
|
Retrieves the current LDAP server host, port, and base DN, and identifies whether the LDAP server is running SSL.
|
|
-setDS[Config]
|
Specifies the LDAP server host, port, and base DN, and specifies whether the LDAP server is running SSL.
Syntax
admconfig [options] -setDSConfig \"host port baseDN ssl\"
Required Arguments
host The LDAP Server host name.
port The LDAP Server port number.
baseDN The LDAP Server base DN.
ssl Specify true or false depending on whether the LDAP server is already using the Secure Sockets Layer (SSL) protocol to communicate with this instance of Administration Server.
On UNIX systems, the backslash character is required before the quotes surrounding the these arguments. If the backslash is not provided, the shell will evaluate the quotes and pass the arguments without the quotes to the command line. As a result, only host will be assigned as a parameter for -setDSConfig, causing the operation to fail.
|
|
-getU[GDSConfig]
|
Retrieves the current user and group LDAP server information, including the host, port, base DN, and authentication DN.
|
|
-setU[GDSConfig]
|
Specifies the host, port, base DN, authentication DN, and authentication password for the instance of Directory Server containing the user and group directory.
You can invoke -setUGDSConfig either with or without arguments. If you invoke this task without any arguments, the Directory Server configuration is reset to the installation defaults.
Syntax
admconfig [options] -setUGDSConfig [\"host port baseDN ssl uid pwd\"]
Optional Arguments
If you want to override the current user and group settings, you must provide all six of the following arguments:
host The host name on which the instance of Directory Serveris running.
port The port number on which the instance of Directory Server is running.
baseDN The base DN for the instance of Directory Server.
ssl Specify true or false depending on whether the instance of Directory Server is already using the Secure Sockets Layer (SSL) protocol to communicate with this instance of Administration Server.
uid The Distinguished Name used to bind to the instance of Directory Server. Example: dn: uid=scarter, ou=people, dc=siroe, dc=com
pwd The password used to bind to the instance of Directory Server.
On UNIX systems, the backslash character is required before the quotes surrounding these arguments. If the backslash is not provided, the shell will evaluate the quotes and pass the arguments without quotes to the command line. As a result, only host will be assigned as a parameter for -setUGDSConfig, causing the operation to fail.
The host, port, baseDN, and ssl arguments are used to create the LDAP URL for the ugdsconfig.dirurl attribute. The uid argument is used to set the ugdsconfig.binddn attribute, and the pwd argument is used to set the ugdsconfig.bindpw attribute.
|
|
-setU[GDSConfig] (continued)
|
Note that the space character is used to parse these six arguments. Therefore, none of the arguments can have spaces in them. To indicate spaces within an argument, use the + character. For example, to specify cn=directory manager as the value for the uid attribute, enter cn=directory+manager. Since the + character is used in place of the space character, you cannot use it as an actual value.
|
|
-getE[rrorLog]
|
Retrieves the path for the server error log file.
|
|
-setE[rrorLog]
|
Specifies the path for the server error log file.
Syntax
admconfig [options] -setErrorLog filename
Required Argument
filename Full path of the new server access log file.
|
|
-getH[osts]
|
Lets you view the host names from which connections are allowed.
|
|
-set[Hosts]
|
Specifies the host names from which connections are allowed.
Syntax
admconfig [options] -setHosts hosts
Required Argument
hosts host names from which connections are allowed.
|
|
-getO[neACLDir]
|
Retrieves the path for the ACL folder.
|
|
-setO[neACLDir]
|
Specifies the path for the ACL folder.
Syntax
admconfig [options] -setOneACLDir directory
Required Argument
directory Path for the ACL folder.
|
|
-getPo[rt]
|
Lets you view the port number that this instance of Administration Server is using.
|
|
-setPo[rt]
|
Specifies the port number that this instance of Administration Server should use.
Syntax
admconfig [options] -setPort port
Required Argument
port Port number that this instance of Administration Server should use.
|
|
-getSe[rverAddress]
|
Retrieves the IP address of this instance of Administration Server.
|
|
-setSe[rverAddress]
|
Specifies the IP address that this instance of Administration Server should use.
Syntax
admconfig [options] -setServerAddress address
Required Argument
address IP address that this server should use.
|
|
-getSy[stemUser]
|
Retrieves the user name that this instance of Administration Server runs as.
|
|
-setSy[stemUser]
|
Specifies the user name that this instance of Administration Server should run as.
Syntax
admconfig [options] -setSuiteSpotUser user
Required Argument
user User ID that this instance should run as.
|
|
-r[estart]
|
Restarts this instance of Administration Server.
|
|
-st[op]
|
Stops this instance of Administration Server.
|
Examples
The following examples demonstrate different uses of admconfig.
This example changes the port number for an instance of Administration Server to 33333, and then restarts the instance. The verbose level option, which controls how much status information is printed to the screen, is set to 5.
-
admconfig -server eastcoast.siroe.com:22222 -user john:password -verbose 5 -setPort 33333 -restart
This example retrieves the hosts from which connections are allowed. The verbose level option is set to 9 (the default value when a number isn't specified).
-
admconfig -ser eastcoast.siroe.com:33333 -u john:password -verb -geth
This example displays the help information for restarting an instance of Administration Server.
-
admconfig -h r
admin_ip.pl
When your computer system's IP address changes, you must update the local Administration Server configuration file and the configuration directory. If you do not enter the new IP address in these locations, you will not be able to start the Administration Server.
A Perl script is provided to help you update these two configurations. The script changes the IP address for an instance of Administration Server in both the local.conf file and the configuration directory. The script is called admin_ip.pl and is stored in the serverRoot/shared/bin folder.
Usage
To run admin_ip.pl follow the instructions for UNIX Systems or Windows NT as appropriate:
On UNIX Systems
In the serverRoot/shared/bin folder, enter
admin_ip.pl Directory_Manager_DN Directory_Manager_password old_IP new_IP [port #]
The old IP address is saved in a file called local.conf.old.
On Windows NT
From the command line go to the serverRoot/shared/bin folder and enter
../../install/perl admin_ip.pl Directory_Manager_DN Directory_Manager_password old_IP new_IP [port #]
The old IP address is saved in a file called local.conf.old.
ldapsearch, ldapmodify, and ldapdelete
These tools allow you to search and modify the user directory. They are stored in the serverRoot/shared/bin folder. For detailed information about how to use these tools, see the iPlanet Directory Server Administrator's Guide.
sec-activate
The sec-activate tool is used to activate and deactivate SSL for an instance of Administration Server. The sec-activate program is stored in the serverRoot/bin/admin/admin/bin folder.
Syntax
sec-activate serverRoot SSLEnabled
Enter information for the following variables:
serverRoot. The server root of the instance of Administration Server on which you want to activate or deactivate SSL.
SSLEnabled. Either on or off.
Example
sec-activate /usr/iplanet/server4 off
sec-migrate
The sec-migrate tool migrates keys and certificates from a pre-4.0 Netscape server to a target iPlanet or Netscape 4.x server. Migrating keys and certificates is useful when you want to use a pre-4.0 SSL certificate with a new server. This tool allows you to use the existing pre-4.0 certificate and its key instead of obtaining a new certificate. The sec-migrate program is stored in the serverRoot/bin/admin/admin/bin directory.
Syntax
sec-migrate src alias dist sie passwd
Enter information for the following variables:
src. Pre-4.0 server root.
alias. Alias of the old key database.
dist. Target server root.
sie. Server instance entry: Name of the server instance to migrate key and certificate information to.
passwd. Password used to generate pre-4.0 key database.
modutil
The modutil tool is a command-line utility for managing PKCS #11 module information stored in secmod.db files or hardware tokens. You can use the tool to perform the following operations:
Adding and deleting PKCS #11 modules
Changing passwords
Setting defaults
Listing module contents
Enabling or disabling slots
Enabling or disabling FIPS-140-1 compliance
Assigning default providers for cryptographic operations
Creating key3.db, cert7.db, and secmod.db security database files.
Security module database management is part of a process that typically involves managing key databases (key3.db files) and certificate databases (cert7.db files). The key, certificate, and PKCS #11 module management process generally begins with creating the keys and key database necessary to generate and manage certificates and the certificate database.
The modutil tool is stored in the serverRoot/shared/bin folder.
Syntax
To run the modutil tool, enter the following command:
modutil task [option]
In this sytax task and [option] are a combination of a task and an option, from Table 8-3 and Table 8-4, each invocation of modutil can take one task and one option. Each option may take zero or more arguments. To view usage information, run the command without options.
Tasks and Options
You can use the modutil tool to perform a number of different tasks. These tasks are specified through the use of commands and options. Commands specify the task to perform. Options modify a task command.
Table 8-3 and Table 8-4 define the task commands and options for modutil.
The "Usage" section on page 145 section gives similar information, but by adminstrator task rather than by command.
Task Commands
Table 8-3 describes what the modutil commands do and what options are available for each. Table 8-4 defines what the options do.
Table 8-3 Task Commands and Options for modutil
|
Commands for Tasks
|
What the Command Does and Options for It
|
|
-add moduleName
|
Adds the named PKCS #11 module to the database.
You can use the following options with this command:
-libfile libraryFile, to specify a DLL or library containing the implementation of the module
-ciphers cipherList, to enable specific ciphers for the module
-mechanisms mechanismList, to specify which security mechanisms this module will be the default service provider for
|
|
-changepw token
|
Changes the password for the named token. If the token has not been initialized, this option initializes it with the supplied password. In this context, the term "password" is equivalent to a personal identification number (PIN).
You can use the following options with this command:
-pwfile passwordFile, to specify a text file that contains the token's current password
-newpwfile newPasswordFile, to specify a text file that contains the token's new password
|
|
-create
|
Creates new secmod.db, key3.db, and cert7.db files.
You can use the following option with this command:
-dbdir dbFolder
If any of these security databases already exist in a specified directory, the modutil tool displays an error message.
|
|
-default moduleName
|
Specifies the security mechanisms for which the named module will be a default provider.
This command uses the following option:
-mechanisms mechanismList
|
|
-delete moduleName
|
Deletes the named module.
Note: You cannot delete the Netscape internal PKCS #11 module.
|
|
-disable moduleName
|
Disables all slots on the named module.
To disable a specific slot, use the following option:
-slot slotName
|
|
-enable moduleName
|
Enables all slots on the named module.
To enable a specific slot, use the following option:
-slot slotName
|
|
-fips true_or_false
|
Enables or disables FIPS-140-1 compliance for the Netscape internal module.
To enable compliance, enter -fips true. To disable compliance, enter -fips false.
|
|
-force
|
Disables the modutil tool's interactive prompts so it can be run from a script. Use this command only after manually testing each planned operation to check for warnings and to ensure that bypassing the prompts will cause no security lapses or loss of database integrity.
|
|
-jar JARfile
|
Adds a new PKCS #11 module to the database. The module must be contained in the named JAR file.
The JAR file identifies all files to install, the module name, mechanism flags, and cipher flags. It should also contain any files to be installed on the target machine, including the PKCS #11 module library and other files such as documentation.
The JAR file uses the iPlanet Server PKCS #11 JAR format. See "JAR Information File" for more information on creating iPlanet JAR files.
You can use the following options with this command:
-installdir installationFolder, to specify the root installation folder for the files contained in the JAR file.
-tempdir temporaryFolder, to specify the folder in which to store temporary files created by the -jar task command
|
|
-list [moduleName]
|
Displays basic information about the contents of the secmod.db file.
To display detailed information about a particular module including its slots and tokens, specify a value for moduleName.
|
|
-undefault moduleName
|
Specifies the security mechanisms for which the named module will not be a default provider.
You specify the security mechanisms by using the following option:
-mechanisms mechanismList
|
Options
The following table describes what the options for modutil do.
Table 8-4 Options for modutil
|
Option
|
What the Option Does
|
|
-ciphers cipherList
|
Enables specific ciphers in a module that you are adding to the database.
CipherList is a colon-delimited list of cipher names. Enclose this list in quotation marks if it contains spaces.
The following cipher is currently available:
|
|
-dbdir dbFolder
|
Specifies a folder in which to access or create security module database files.
On UNIX systems, the Security Module Database Tool defaults to the user's iPlanet or Netscape folder. Windows NT has no default folder, so you must use -dbdir to specify a folder.
|
|
-installdir InstallationDir
|
Specifies the root installation folder for the files supplied via the -jar JAR-file command.
The InstallationDir folder should be one in which it is appropriate to store dynamic library files—for example, a server root.
|
|
-libfile libraryFile
|
Specifies a DLL (Dynamic Link Library) or library file containing the implementation of the PKCS #11 module that is being added to the database. Use a complete path to identify the file.
|
|
-mechanisms mechanismList
|
Specifies the security mechanisms for which a particular module will be the default provider.
The MECHANISM_LIST is a colon-separated list of mechanism names. Enclose this list in quotation marks if it contains spaces.
The module becomes a default provider for the listed mechanisms when those mechanisms are enabled. If more than one module is assigned as a mechanism's default provider, the mechanism's default provider is listed as undefined.
The following mechanisms are currently available:
RSA
DSA
RC2, RC4, RC5
DES
DH
FORTEZZA
SHA1
MD2, MD5
RANDOM (for random number generation)
FRIENDLY (for certificates that are publicly readable).
|
|
-newpwfile newPasswordFile
|
Specifies a text file containing a token's new password. This allows automatic updating of the password when using the -changepw command.
|
|
-nocertdb
|
Instructs modutil to not open the certificate or key databases. This has several effects:
When used with the -changepw command, no one will be able to set or change the password on the iPlanet internal module, because the password is stored in key3.db.
When used with the -create command, only a secmod.db file will be created; cert7.db and key3.db will not be created.
When used with the -jar command, signatures on the JAR file will not be checked.
|
|
-pwfile passwordFile
|
Specifies a text file containing a token's current password. This allows automatic entry of the password when using the -changepw command.
|
|
-slot slotName
|
Specifies a particular slot to enable or disable when using the -enable or -disable commands.
|
|
-tempdir temporaryFolder
|
Specifies a folder in which to store temporary files created by the -jar command. If a temporary folder is not specified, the current folder is used.
|
Usage
Tasks that you can perform using the modutil toolare listed here in the order you might do them, with the command and any options you use to perform them. The options and arguments in square brackets are optional; those without square brackets are required.
Creating a set of security management database files (key3.db, cert7.db, and secmod.db):
-
-create [-dbdir dbFolder]
Displaying basic module information or detailed information about the contents of a given module:
-
-list [moduleName]
Adding a PKCS #11 module. This includes specifying a library file, enabling ciphers, and setting default provider status for various security mechanisms:
-
-add moduleName -libfile libraryFile [-ciphers cipherList] [-mechanisms mechanismList]
Adding a PKCS #11 module from a JAR file:
-
-jar JARfile -installdir installationFolder [-tempdir temporaryFolder]
Deleting a specific PKCS #11 module from a security module database:
-
-delete moduleName
Initializing or changing a token's password:
-
-changepw token [-pwfile passwordFile][-newpwfile newPasswordFile]
Setting the default provider status of various security mechanisms in an existing PKCS #11 module:
-
-default moduleName -mechanisms mechanismList
Clearing the default provider status of various security mechanisms in an existing PKCS #11 module:
-
-undefault moduleName -mechanisms mechanismList
Enabling a specific slot or all slots within a module:
-
-enable moduleName [-slot slotName]
Disabling a specific slot or all slots within a module:
-
-disable moduleName [-slot slotName]
Enabling or disabling FIPS-140-1 compliance within the Netscape Communicator internal module:
-
-fips true_or_false
Disabling interactive prompts for the modutil tool in order to support scripted operation:
-
-force
JAR Information File
JAR (Java Archive) is a platform-independent file format that aggregates many files into one. JAR files are used by the modutil tool to install PKCS #11 modules. When modutil uses a JAR file, a special JAR information file must be included. This information file contains special scripting instructions and must be specified in the JAR file's MANIFEST file. Although the information file can have any name, you specify it by using the Pkcs11_install_script METAINFO command. To declare this METAINFO command in the MANIFEST file, include it in a text file that is passed to the iPlanet Signing Tool.
Sample METAINFO Tag and JAR Information File
If a PKCS #11 installer script was stored in the information file pk11install, the text file for the iPlanet Signing Tool would contain the following METAINFO tag:
+ Pkcs11_install_script: pk11install
The following is an example of a JAR information file which contains instructions for installing a PKCS #11 module on different platforms. The syntax used in the file is explained in "JAR Information File Syntax."
|
ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc }
Platforms {
WINNT::x86 {
ModuleName { "Fortezza Module" }
ModuleFile { win32/fort32.dll }
DefaultMechanismFlags{0x00000001}
CipherEnableFlags{0x00000001}
Files {
win32/setup.exe {
Executable
RelativePath { %temp%/setup.exe }
}
win32/setup.hlp {
RelativePath { %temp%/setup.hlp }
}
win32/setup.cab {
RelativePath { %temp%/setup.cab }
}
}
}
WIN95::x86 {
EquivalentPlatform {WINNT::x86}
}
SUNOS:5.5.1:sparc {
ModuleName { "Fortezza UNIX Module" }
ModuleFile { unix/fort.so }
DefaultMechanismFlags{0x00000001}
CipherEnableFlags{0x00000001}
Files {
unix/fort.so {
RelativePath{%root%/lib/fort.so}
AbsolutePath{/usr/local/netscape/lib/fort.so}
FilePermissions{555}
}
xplat/instr.html {
RelativePath{%root%/docs/inst.html}
AbsolutePath{/usr/local/netscape/docs/inst.html}
FilePermissions{555}
}
}
}
IRIX:6.2:mips {
EquivalentPlatform { SUNOS:5.5.1:sparc}
}
}
|
|
JAR Information File Syntax
Creating a JAR information file involves writing a script that specifies which tasks to perform when installing a module. In order to specify different module installation procedures for different platforms, you use keys, predefined commands and options that modutil interprets.
Keys are case-insensitive strings that are grouped into three categories:
The following sections describe the function of each of these three categories and list the keys contained in each one.
Global Keys
Global keys define the platform-specific sections of the JAR information file. There are two global keys: ForwardCompatible and Platforms.
ForwardCompatible is an optional key that specifies a list of system architectures and operating systems that are compatible with later versions of the same architectures and operating systems. If the platform that modutil is installing the module on is not specified by the Platforms key, then the ForwardCompatible list is checked for any platforms that have the same OS and architecture in an earlier version. If one is found, its attributes are used for the current platform.
The ForwardCompatible key uses the following format:
ForwardCompatible { IRIX:6.2:mips SUNOS:5.5.1:sparc}
The platforms listed between the braces must have entries within the Platforms key.
Platforms is a required key that specifies a list of platforms. Each entry in the list is itself a key-value pair: the key is the name of the platform and the value list contains various attributes of the platform. The ModuleName, ModuleFile, and Files attributes must be specified for each platform unless an EquivalentPlatform attribute is specified. For more information, see "Per-Platform Keys."
The platform string is in the following format:
system name:OS release:architecture.
On non-UNIX operating systems, OS release is an empty string.
The modutil program obtains the system name, OS release, and architecture values from the system on which the modutil tool is running using low-level code written by Netscape. The following system names and platforms are currently recognized by the low-level Netscape code:
AIX (rs6000)
BSDI (x86)
FREEBSD (x86)
HPUX (hppa1.1)
IRIX (mips)
LINUX (ppc, alpha, x86)
MacOS (PowerPC)
NCR (x86)
NEC (mips)
OS2 (x86)
OSF (alpha)
ReliantUNIX (mips)
SCO (x86)
SOLARIS (sparc)
SONY (mips)
SUNOS (sparc)
UNIXWare (x86)
WIN16 (x86)
WIN95 (x86)
WINNT (x86)
Here are some examples of valid platform strings:
IRIX:6.2:mips
SUNOS:5.5.1:sparc
Linux:2.0.32:x86
WIN95::x86.
Per-Platform Keys
These keys have meaning only within an entry in the Platforms list.
ModuleName is a required key that specifies the common name for the module. This name acts as a reference to the module for Netscape Communicator, the modutil tool, servers, or any other program that uses the iPlanet security module database.
ModuleFile is a required key that names the PKCS #11 module file (DLL or .so) for this platform. The file name should be a path that is relative to the JAR file location.
DefaultMechanismFlags is an optional key that specifies mechanisms for which this module will be a default provider. This key-value pair is a bitstring specified in hexadecimal (0x) format. It is constructed as a bitwise OR of the string constants listed in Table 8-5. If you omit the DefaultMechanismFlags entry, the value defaults to 0x0.
Table 8-5 Mechanisms That You Can Specify Using DefaultMechanismFlags
|
Mechanism
|
Hexadecimal Bitstring Value
|
|
RSA
|
0x00000001
|
|
DSA
|
0x00000002
|
|
RC2
|
0x00000004
|
|
RC4
|
0x00000008
|
|
DES
|
0x00000010
|
|
DH
|
0x00000020
|
|
FORTEZZA
|
0x00000040
|
|
RC5
|
0x00000080
|
|
SHA1
|
0x00000100
|
|
MD5
|
0x00000200
|
|
MD2
|
0x00000400
|
|
RANDOM
|
0x08000000
|
|
FRIENDLY
|
0x10000000
|
|
OWN_PW_DEFAULTS
|
0x20000000
|
|
DISABLE
|
0x40000000
|
CipherEnableFlags is an optional key that specifies ciphers that are provided by this module but not by iPlanet products. You use this key if you want to enable these ciphers for iPlanet products. The key is a bitstring specified in hexadecimal (0x) format. It is constructed as a bitwise OR of the following string constants. If you omit the CipherEnableFlags entry, the value defaults to 0x0. The only key that is provided right now is for Fortezza:
FORTEZZA: 0x00000001
Files is a required key that lists the files that need to be installed for this module. Each entry in the file list is a key-value pair. The key includes the path to the file that is contained in the JAR archive and the value list contains the attributes of the file. At a minimum, you must specify either RelativePath or AbsolutePath for each file. If desired, you can specify additional attributes. For more information, see "Per-File Keys."
The EquivalentPlatform key specifies that the attributes of the named platform should also be used for the current platform. Using this key saves time when more than one platform uses the same settings.
Per-File Keys
These keys have meaning only within an entry in a Files list. At a minimum, RelativePath or AbsolutePath must be specified. If both are specified, the relative path is tried first, and the absolute path is used only if a relative root folder is not provided by modutil.
The RelativePath key specifies the destination path of the file, relative to a folder indicated at installation. You can assign values for two variables in the relative path, "%root%" and "%temp%". At run time, "%root%" is replaced with a folder in which files should be installed, such as the server's root folder. The "%temp%" folder is created at the beginning of the installation and destroyed at the end.
The purpose of "%temp%" is to hold executable files (such as setup programs) or files that are used by these programs. For example, a Windows installation might consist of a setup.exe installation program, a help file, and a .cab file containing compressed information. All of these files could be installed in the temporary folder. Files destined for the temporary folder are in place before any executable file is launched. They are not deleted until all executable files have finished.
The AbsolutePath key specifies the destination of the file as an absolute path. If both RelativePath and AbsolutePath are specified, modutil attempts to use the relative path. If it is unable to determine a relative path, it uses the absolute path.
The Executable key specifies that a file is to be executed during the course of the installation. Typically this key is used to identify a setup program provided by a module vendor. The setup program itself is specified by the RelativePath or AbsolutePath key.
For example, to specify that the setup.exe program (located in the %temp% folder) is an executable file, you would include the following lines in your JAR information file:
Executable
RelativePath { %temp%/setup.exe }
More than one file can be specified as executable, in which case the files are run in the order in which they are listed in the script file. Use the Executable key before a RelativePath or AbsolutePath key to indicate the order in which the files are to be run.
The FilePermissions key specifies the access permissions to apply to a file. The modutil program interprets the key as a string of octal digits, following the standard UNIX format. This key is a bitwise OR of the string constants listed in Table 8-6. For example, to specify Read and Execute access for all users, you would enter 555 (bitwise 400 + 100 + 040 + 010 + 004 + 001).
The following table lists the file permissions that you can specify using FilePermissions.
Table 8-6 File Permissions That You Can Specify Using FilePermissions
|
File Permission
|
Bitstring Value
|
|
User Read
|
400
|
|
User Write
|
200
|
|
User Execute
|
100
|
|
Group Read
|
040
|
|
Group Write
|
020
|
|
Group Execute
|
010
|
|
Other Read
|
004
|
|
Other Write
|
002
|
|
Other Execute
|
001
|
Some platforms may not understand these permissions. The permissions are applied only if they make sense for the current platform. If this key is omitted, a default value of 777 (Read, Write and Execute for all users) is assumed.
Examples of Using modutil
This section includes examples of using modutil to perform the following tasks:
Creating Database Files
You could enter something like the following example to create a set of security management database files in a directory:
modutil -create -dbdir C:\databases
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool creates the databases and displays the following:
Creating "C:\databases\key3.db"...done.
Creating "C:\databases\cert7.db"...done.
Creating "C:\databases\secmod.db"...done.
Displaying Module Information
This example uses modutil to retrieve detailed information about a specific module:
modutil -list "iPlanet Internal PKCS #11 Module" -dbdir C:\databases
The modutil tool displays information similar to this:
Using database directory C:\databases...
--------------------------------------------------------
Name: Netscape Internal PKCS #11 ModuleLibrary file:
**Internal ONLY module**
Manufacturer: Netscape Communications Corp.
Description: Communicator Internal Crypto Svc
PKCS #11 Version 2.0
Library Version: 4.0
Cipher Enable Flags: None
Default Mechanism Flags: RSA:DSA:RC2:RC4:DES:SHA1:MD5:MD2
Slot: Communicator Internal Cryptographic Services Version 4.0
Manufacturer: Netscape Communications Corp
Type: Software
...
Setting a Default Provider
You could enter something like the following example to make a specific module the default provider for the RSA, DSA, and RC2 security mechanisms:
modutil -default "Cryptographic Module" -dbdir C:\databases
-mechanisms RSA:DSA:RC2
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool makes the change and displays the following:
Using database directory C:\databases...
Successfully changed defaults.
Enabling a Slot
You could enter something like the following example to enable a particular slot in a module:
modutil -enable "Cryptographic Module" -slot "Cryptographic Reader"
-dbdir C:\databases
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool enables the slot and displays the following:
Using database directory C:\databases...
Slot "Cryptographic Reader" enabled.
Enabling FIPS Compliance
You could enter something like the following example to enable FIPS-140-1 compliance in iPlanet Administration Server's internal module:
modutil -fips true
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool enables FIPS compliance and displays the following:
FIPS mode enabled.
Adding a Cryptographic Module
You could enter something like the following example to add a new cryptographic module to the database:
C:\modutil> modutil -dbdir "C:\databases" -add "Cryptorific Module"
-libfile "C:\winnt\system32\crypto.dll" -mechanisms
RSA:DSA:RC2:RANDOM
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool adds the module and displays the following:
Using database directory C:\databases...
Module "Cryptorific Module" added to database.
C:\modutil>
Installing a Cryptographic Module From a JAR File
You could enter something like the following example to install a cryptographic module from an installation script. The example uses this script:
|
Platforms {
WinNT::x86 {
ModuleName { "SuperCrypto Module" }
ModuleFile { crypto.dll }
DefaultMechanismFlags{0x0000}
CipherEnableFlags{0x0000}
Files {
crypto.dll {
RelativePath{ %root%/system32/crypto.dll }
}
setup.exe {
Executable
RelativePath{ %temp%/setup.exe }
}
}
}
Win95::x86 {
EquivalentPlatform { Winnt::x86 }
}
}
|
|
To install from the script, use the following command. The root directory should be the Windows root directory (for example, C:\Windows, or C:\Winnt).
C:\modutil> modutil -dbdir "C:\databases" -jar install.jar
-installdir "C:\winnt"
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool installs the module and displays the following:
Using database directory C:\databases...
This installation JAR file was signed by:
----------------------------------------------
**SUBJECT NAME**
C=US, ST=California, L=Mountain View, CN=SuperCrypto Inc.,
OU=Digital ID Class 3 - Netscape Object Signing,
OU="www.verisign.com/repository/CPS Incorp. by Ref.,LIAB.LTD(c)9 6",
OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign,
OU=VeriSign Object Signing CA - Class 3 Organization, OU="VeriSign,
Inc.", O=VeriSign Trust Network **ISSUER NAME**,
OU=www.verisign.com/CPS Incorp.by Ref. LIABILITY LTD.(c)97 VeriSign,
OU=VeriSign Object Signing CA - Class 3 Organization, OU="VeriSign,
Inc.", O=VeriSign Trust Network
----------------------------------------------
Do you wish to continue this installation? (y/n)
After you press y, the tool displays the following:
Using installer script "installer_script"
Successfully parsed installation script
Current platform is WINNT::x86
Using installation parameters for platform WinNT::x86
Installed file crypto.dll to C:/winnt/system32/crypto.dll
Installed file setup.exe to ./pk11inst.dir/setup.exe
Executing "./pk11inst.dir/setup.exe"...
"./pk11inst.dir/setup.exe" executed successfully
Installed module "SuperCrypto Module" into module database
Installation completed successfully
Changing the Password on a Token
You could enter something like the following example to change the password for a security device in use by a module.
C:\modutil> modutil -dbdir "C:\databases" -changepw "Administration
Server Certificate DB"
Before running this program, the modutil tool displays a warning:
WARNING: Performing this operation while an iPlanet product is running could cause corruption of your security databases. If an iPlanet product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter> to continue:
After you press Enter, the tool changes the password and displays the following:
Using database directory C:\databases...
Enter old password:
After you enter the old password, the tool displays the following:
Enter new password:
After you enter the new password, the tool displays the following:
Re-enter new password:
After you re-enter the new password, the tool displays the following:
Token "Administration Server Certificate DB" password changed
successfully.