Chapter 8   Administration Server Command-Line Tools

The command-line tools described in this chapter come with Sun ONE Administration Server. You can use these utilities to configure an instance of Administration Server without launching Sun ONE Server Console:

• mpsadmconfig
• mpsadmserver admin_ip
• ldapsearch, ldapmodify, and ldapdelete

This chapter tells you how to use the command-line tools.

mpsadmconfig

The mpsadmconfig(1M) utility allows you to configure an instance of Administration Server using the command line instead of using the Sun ONE Server Console. When using the product delivered in Solaris package format, use mpsadmconfig(1M) to modify network, access, encryption, or directory settings.

When using the product not delivered in Solaris package format, use the admconfig utility stored under ServerRoot/bin/admin and has the same syntax as mpsadmconfig(1M).

Syntax for mpsadmconfig

/mpsadmconfig [options] task [args] [task2] [args] [task3] [args] ...

The options that you can use with mpsadmconfig(1M) are described in the section that follows. The tasks that you can perform with mpsadmconfig(1M), 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 mpsadmconfig(1M) 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 mpsadmconfig(1M). For example, the following option commands specify that mpsadmconfig(1M) should establish an encrypted connection with eastcoast.example.com on port 1389.

/usr/sbin/mpsadmconfig -enc -ser eastcoast.example.com:1389

Table 8-1    Options You Can Use With mpsadmconfig(1M)  

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 is not 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 are 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 mpsadmconfig(1M) 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 mpsadmconfig(1M). If you use the -i[nputFile] option command to specify an input file, mpsadmconfig(1M) runs the tasks contained in that file first. The mpsadmconfig(1M) 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 mpsadmconfig(1M)  

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 /usr/sbin/mpsadmconfig [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 evaluates the quotes and pass the arguments without quotes to the command line. As a result, only start is 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 /usr/sbin/mpsadmconfig [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 evaluates the quotes and pass the arguments without quotes to the command line. As a result, only start is assigned as a parameter for -viewErrorLogEntries, causing the operation to fail.
-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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [options] -setAdminUID uid Required Argument uid The new Administration Server Administrator's user ID.
-setAdminP[wd]	Specifies the Administration Server Administrator's password. Syntax /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 evaluates the quotes and pass the arguments without the quotes to the command line. As a result, only host is 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 /usr/sbin/mpsadmconfig [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 Server is 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=dfauvarque, ou=people, dc=example, 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 evaluates the quotes and pass the arguments without quotes to the command line. As a result, only host is 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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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 /usr/sbin/mpsadmconfig [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.

/usr/sbin/mpsadmconfig -server eastcoast.example.com:22222 -user josu: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).

/usr/sbin/mpsadmconfig -ser eastcoast.example.com:33333 -u josu:password -verb -geth

• This example displays the help information for restarting an instance of Administration Server.

/usr/sbin/mpsadmconfig -h r

mpsadmserver admin_ip

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 cannot subsequently start the Administration Server.

When using the product delivered in Solaris package format, use the mpsadmserver(1M) utility with the admin_ip subcommand to update these two configurations.

When using the product not delivered in Solaris package format, 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 the command follow the instructions for the appropriate platform:

On UNIX Systems

Enter the command appropriate for the version you installed, such as the following for Solaris:

/usr/sbin/mpsadmconfig admin_ip 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 Systems

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. These tools are documented in Solaris online manual pages ldapsearch(1), ldapmodify(1), and ldapdelete(1). Expanded versions are provided with the Sun ONE Directory Server Resource Kit and documented in the Sun ONE Directory Server Resource Kit Tools Reference.