Command Line Administration Tool. Extensis 6

Command Line Administration Tool

Universal Type Server contains a command line tool that exposes a number of the functions of the Server

Administration application in command line format.

In some cases, this tool allows for more granular control of certain operations and allows these operations to be scripted.

The tool script name is esp-admin and is available in both batch (.bat) and shell script (.sh) formats for use on Windows and Macintosh operating systems, respectively.

The tool resides inside of the Universal Type Server’s applications subfolder. For example:

Windows: C:\Program Files\Extensis\Universal Type Server\applications\

Mac OS X: Applications/Extensis/Universal Type Server/applications/

NOTE

When running the esp-admin.bat using the Windows command prompt, any non-ASCII characters are displayed as question marks. This can cause issues when displaying items that allow Unicode characters, such as the

Bonjour server name.

Viewing Server Settings with the Command Line Tool

If you are unable to use the web application to initially open the Server Administration application, you can use the command line tool to view pertinent server settings. This can happen if you are installing onto a headless server, and there is a port conflict with the default Server Administration port.

To view server settings with the command line tool on Windows:

1. Open a Command Prompt window.

Click Start > Run, type cmd, and press Enter.

2. At the command prompt enter: cd C:\Program Files\Extensis\Universal Type Server\applications\

3. Enter the following command to list server settings: esp-admin -username administrator -password password -getserversettings

NOTE

If you have changed the default administrator password, enter it after

-password in the command.

To view the server settings with the command line tool on Mac OS X:

1. Start the Terminal application located in the Utilities folder inside the Applications folder.

2. At the prompt, enter: cd "/Applications/Extensis/Universal Type Server/applications/"

3. Enter the following command to list server settings: sudo ./esp-admin.sh -username administrator -password password

-getserversettings

The server lists a number of important server settings, including repository location, backup location, and the ports currently in use. The port listed after esp.port.admin-web-app= is the port currently in use for the

Server Administration application.

- 53 -

Properties Files

Many commands require the inclusion of data in a “properties” file to function properly. These files are basically lists of options and the selected values for those options.

Properties files must be saved as standard ASCII text files, and cannot include any high ASCII characters.

The following is an example of the contents of a properties file.

esp.backup.location=C://backups/ esp.backup.filename=mybackup.tar

esp.option.backup.stayinquiescentmode=false

Note: Paths in the properties file must be specified differently than they are in Windows. Use the form <drive_ letter>://<folder>/<folder>/<file>; for example, C://backups/ or

C://Program Files/Extensis/Universal Type Server/data/vault.

Properties files are used with the following commands:

backupdatastore (see backupdatastore on the next page.)

createdatastore (see createdatastore on page 57.)

moverepository (see moverepository on page 61.) restoredatastore (see restoredatastore on page 61.)

Specifying a Username and Password

Almost every command line operation requires the addition of a username and password that has administrative privileges.

The username and password can be specified in the command line each time a command is executed, or it can be specified as an environment variable.

The two environment variables that can be set are: l

ESP_ADMIN_USER, which by default is set to the value administrator, the Server Administrator l username; and

ESP_ADMIN_PW, which by default is set to the value password, the default Server Administrator password.

The following is an example of specifying the username and password in the Windows command line when adding a serial number: esp-admin ESP_ADMIN_USER ESP_ADMIN_PW -addserialnumber XXXX-1234-ABCD-EFGH-

IJKL-MNOP

For assistance setting environment variables, see the documentation for your operating system.

- 54 -

Commands

backupdatastore

-backupdatastore [-properties pro perties.txt] [-force]

Backs up the datastore.

-properties: use properties specified in the file properties.txt.

-force: automatically accept all interactive confirmation prompts.

The properties file is a plain text file that can contain any or all of the following optional settings: esp.backup.location=full_backup_path

The complete path to the backup directory. If not specified, the default backup directory is used.

Note: Paths in the properties file must be specified differently than they are in Windows. Use the form

<drive_letter>://<folder>/<folder>/<file>; for example, C://backups/ or

C://Program Files/Extensis/Universal Type Server/data/vault.

esp.backup.filename=filename.zip

Name of the backup file. The backup is stored as a .ZIP compressed archive; you must include the .ZIP

extension in the filename. If you don’t specify a filename, the backup will be named using the pattern year_mo_dy_hr_mn.zip.

esp.option.backup.stayinquiescentmode=bo o lean

Specifies whether the server will be left in “quiescent” or standby mode after the backup is complete. Valid values are true or false; the default is false.

Use this command to backup the datastore. This command can be used alone, or with a properties file that contains multiple parameters. In addition, the option to dismiss all interactive confirmation prompts is controlled with the force option.

-backupdatastore -properties pro perties.txt -fo rce

- 55 -

The following properties can be specified in the properties file.

Property esp.backup.location

Description

The full, complete directory path to where the backup file will be placed. If not specified, the default backup directory is used.

esp.backup.filename

Name of the backup file. If not specified, the server will use the default backup file naming convention of yyyy_mm_dd_hh_mm.zip

esp.option.backup.stayinquiescentmode Specifies that the server be left in quiescent (standby) mode after backup. Valid values are true or false.

Default value is false.

Required

No

No

No

Note: Paths in the properties file must be specified differently than they are in Windows. Use the form

<drive_letter>://<folder>/<folder>/<file>; for example, C://backups/ or

C://Program Files/Extensis/Universal Type Server/data/vault.

Windows usage example:

esp-admin -username ssmith -password stevespass -backupdatastore -properties properties.txt -force

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -backupdatastore

-properties properties.txt -force

canceldatastoreoperation

This command cancels any current datastore operation, and does not have any parameters.

-canceldatastoreoperation

Windows usage example:

esp-admin -username ssmith -password stevespass -canceldatastoreoperation

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass

-canceldatastoreoperation

checkdatastoreoperationstatus

This command checks the status of any current datastore operations, and does not have any parameters.

-checkdatastoreoperationstatus

Windows usage example:

esp-admin -username ssmith -password stevespass -checkdatastoreoperationstatus

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass

-checkdatastoreoperationstatus

- 56 -

createdatastore

-createdatastore -properties pro perties.txt [-force]

Creates a new database with the properties specified in properties.txt.

esp.repository.directory=fo lder_name

Required. This is the name of the folder that contains the datastore.

esp.repository.type=esp.repository.type.vault

Required. Currently, esp.repository.type.vault is the only supported repository type.

esp.database.driver=esp.database.driver.PostgreSQL

Required. Currently, esp.database.driver.PostgreSQL is the only supported database driver.

esp.database.username=user

Optio nal. The database user’s name.

esp.database.password=passwo rd

Optio nal. user’s password to access the database.

esp.database.hostport=ho st:po rt

Optio nal. Host and port used to connect to the database, in the form host:port. host can be any valid host identifier: the word localhost, an IP address, or a server name; port is the JBoss Web App port.

esp.database.datapath=full_path_to _database

Optio nal. If not specified, the default location is used.

esp.option.backup.stayinquiescentmode=bo o lean

Optio nal.

This command creates a new datastore using a properties file. Before using this command, be sure to have a backup of your current datastore.

This command relies upon the creation of a pro perties file (see Properties Files on page 54). In addition,

the option to dismiss all interactive confirmation prompts is controlled with the force option.

-createdatastore -properties pro perties.txt -force

- 57 -

The following properties can be specified in the properties file.

Property esp.repository.directory

Description

The top level of the datastore.

esp.repository.type

esp.database.driver

The only supported value is esp.repository.type.vault.

Logical name of database type to use. Currently the only supported value is esp.database.driver.PostgreSQL.

esp.database.username

esp.database.password

esp.database.hostport

The database user name.

The database password.

Host and port used to connect to the database.

Formatted host:port, for example: localhost:3487.

Path to the database.

esp.database.datapath

esp.option.backup.stayinquiescentmode Specifies that the server be left in quiescent (standby) mode after creating the datastore. Valid values are true or false. Default value is false.

Required

Yes

Yes

Yes

No

No

No

No

No

Note: Paths in the properties file must be specified differently than they are in Windows. Use the form

<drive_letter>://<folder>/<folder>/<file>; for example, C://backups/ or

C://Program Files/Extensis/Universal Type Server/data/vault.

Windows usage example:

esp-admin -username ssmith -password stevespass -createdatastore -properties properties.txt -force

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -createdatastore

-properties properties.txt -force

directorysynchronize

With directory integration, Universal Type Server is bound to a Directory Service. This command synchronizes Universal Type Server with the Directory Service.

-directorysynchronize

Windows usage example:

esp-admin -username ssmith -password stevespass -directorysynchronize

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass

-directorysynchronize

forcelogouts

This command forces the logout of a specific user as identified by session ID (or GUID).

To identify a user’s session ID, use the getlogins command (see getlogins on the next page). This

command returns a list containing the username, long username, IP address of login client, the login time, as well as the necessary session ID which is also known as the user GUID.

-forcelogouts sessio nID

- 58 -

Windows usage example:

esp-admin -username ssmith -password stevespass -forcelogouts 28203500-FA5D-

8A0A-27BC-E7996E17EDC1

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -forcelogouts

28203500-FA5D-8A0A-27BC-E7996E17EDC1

forcelogoutswithfile

This command forces the logout of a list of users contained within a userlogout text file. The text file must contain one user session ID (or GUID) per line.

To identify a user’s session ID, use the getlogins command. This command returns a list containing the username, long username, IP address of login client, the login time, as well as the necessary session ID which is also known as the user GUID.

-forcelogoutswithfile -file userlo go ut.txt

Windows usage example:

esp-admin -username ssmith -password stevespass -forcelogoutswithfile -file userlogout.txt

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass

-forcelogoutswithfile -file userlogout.txt

getlogins

This command lists all users currently logged in to the Type Server and does not have any parameters.

This command returns a list containing the username, long username, IP address of login client, the login time, and the session ID which is also known as the user GUID. The user session ID can be used to force the logout of specific users using the forecelogouts or forcelogoutswithfile commands (see

forcelogouts on the previous page and forcelogoutswithfile above).

-getlogins

Windows usage example:

esp-admin -username ssmith -password stevespass -getlogins

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -getlogins

- 59 -

getserversettings

This command displays a list of the current server settings.

-getserversettings

The following is a list of server properties displayed by this command:

Property esp.container.autostart

esp.core.bonjour.name

Description

This is the autostart setting of the server: enabled or disabled.

The current Bonjour name of the server.

esp.core.repository.location

The location of the server vault.

esp.core.service.backup.directory Directory where backup files are to be written. This path should allow changes.

esp.core.service.backup.schedule

Backup schedule expression. Expression must adhere to the formats supported by Quartz.

esp.core.service.logging.level

The logging level of the server: error, warn, info, or debug.

esp.core.service.logging.location Directory where logs are to be written. This path should allow changes.

esp.core.service.state

The current state of the server: started, stopped, or standby.

esp.port.admin-web-app The Server Administration port, also called the Jetty Web App port.

esp.port.bootstrap-jnp esp.port.http

The Bootstrap JNP Server Bind Address port.

The User Management port. This port is also used for client connection and also called the JBoss HTTP / Web Service port.

esp.port.jmx-pooled esp.port.jmx-rmi esp.port.rmi-naming esp.port.webservice

The JMX Pooled Port.

The JMX RMI Object Port.

The RMI Naming Service port.

The JBoss Webservice port.

Windows usage example:

esp-admin -username ssmith -password stevespass -getserversettings

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -getserversettings

- 60 -

moverepository

This command moves the font vault (also called the repository) to a new location. This command relies

upon the creation of a properties.txt file (see Properties Files on page 54).

-moverepository -properties pro perties.txt

The following properties can be specified in the properties file.

Property esp.repository.directory

Description

The top level of the datastore.

esp.repository.type

The only supported value is esp.repository.type.vault.

esp.option.backup.stayinquiescentmode Specifies that the server be left in quiescent (standby) mode after moving the datastore. Valid values are true or false. Default value is false.

Required

Yes

Yes

No

Note: Paths in the properties file must be specified differently than they are in Windows. Use the form

<drive_letter>://<folder>/<folder>/<file>; for example, C://backups/ or

C://Program Files/Extensis/Universal Type Server/data/vault.

Windows usage example:

esp-admin -username ssmith -password stevespass -moverepository -properties properties.txt

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -moverepository

-properties properties.txt

reapseats

This command synchronously removes any unused client seats that have not synchronized with the server within 30 days.

-reapseats

Windows usage example:

esp-admin -username ssmith -password stevespass -reapseats

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -reapseats

restoredatastore

WARNING restoredatastore is destructive; it will replace your current datastore with the contents of the specified backup. Be sure this is what you want to do before you execute restoredatastore.

Use this command to restore a backup copy of the datastore. This command relies upon the creation of a properties.txt

file (see Properties Files on page 54). In addition, the option to dismiss all interactive confirmation

prompts is controlled with the force option.

-restoredatastore -properties pro perties.txt -fo rce

- 61 -

The following properties can be specified in the properties file.

Property esp.backup.location

Description

Directory of the backup file. If not specified, the default server backup directory is assumed.

esp.backup.filename

esp.repository.directory

esp.repository.type

esp.database.driver

Name of the backup file.

The top level of the datastore.By default this is

Applications/Extensis/Universal Type

Server/data/vault on Macintosh or C:\Program

Files\Extensis\Universal Type

Server\data\vault on Windows.

The only supported value is esp.repository.type.vault.

Logical name of database type to use. Currently the only supported value is esp.database.driver.PostgreSQL.

The database user name.

esp.database.username

esp.database.password

esp.database.hostport

The database password.

Host and port used to connect to the database.

Formatted host:port, for example: localhost:3487.

Path to the database.

esp.database.datapath

esp.option.backup.stayinquiescentmode Specifies that the server be left in quiescent (standby) mode after restoring the datastore. Valid values are true or false. Default value is false.

Required

No

Yes

Yes

Yes

Yes

No

No

No

No

No

Note: Paths in the properties file must be specified differently than they are in Windows. Use the form

<drive_letter>://<folder>/<folder>/<file>; for example, C://backups/ or

C://Program Files/Extensis/Universal Type Server/data/vault.

Windows usage example:

esp-admin -username ssmith -password stevespass -restoredatastore -properties properties.txt -force

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -restoredatastore

-properties properties.txt -force

- 62 -

setautostart

This command sets the whether the Type Server launches automatically when the computer starts. This command takes a single parameter with one of two values: enabled or disabled.

-setautostart value

Windows usage example:

esp-admin -username ssmith -password stevespass -setautostart enabled

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setautostart enabled

setbackupdirectory

This command sets the location where backups are stored. The path must a full path and the target location must be writable.

-setbackupdirectory fullpath

Windows usage example:

esp-admin -username ssmith -password stevespass -setbackupdirectory c:\this\is\my\backup\

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setbackupdirectory

"/Applications/Extensis/Universal Type Server/mybackups/"

setlogdirectory

This command sets the location where log files are stored. The path must be a complete path and the user must have write access to the target location.

-setlogdirectory fullpath

Windows usage example:

esp-admin -username ssmith -password stevespass -setlogdirectory c:\this\is\my\backup\

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setlogdirectory

"/Applications/Extensis/Universal Type Server/mybackups/"

setlogginglevel

This command sets the logging level of the server and can be set to one of four case-sensitive values: l l l l error warn info debug

-setlogginglevel value

Windows usage example:

esp-admin -username ssmith -password stevespass -setlogginglevel info

- 63 -

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setlogginglevel info

setmaxbackuplogs

This command sets the maximum number of log files that are backed up.

-setmaxbackuplogs co unt

count must be a whole number greater than zero. The default is 10.

Windows usage example:

esp-admin -username ssmith -password stevespass -setmaxbackuplogs 15

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setmaxbackuplogs

7

setport

This command is used to set the ports to which clients connect, the User Management port

(esp.port.http) as well as the Server Administration port (esp.port.admin-web-app).

The values must be between 1 and 65536 and not conflict with any other ports currently in use.

-setport po rtname=value

To change the client connection and the User Management application port (JBoss HTTP / Web Service port), use the following command: esp-admin -username administrator -password password -setport esp.port.http=PORT_NUM

Windows usage example:

esp-admin -username ssmith -password stevespass -setport esp.port.http=8080

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setport esp.port.http=8080

To change the Server Administration application port (Jetty Web App port), use the following command: esp-admin -username administrator -password password -setport esp.port.admin-web-app=PORT_NUM

Windows usage example:

esp-admin -username ssmith -password stevespass -setport esp.port.admin-web-app=18081

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setport esp.port.admin-web-app=18081

setservername

This command sets the name used by Bonjour to advertise to clients.

-setservername name

- 64 -

Windows usage example:

esp-admin -username ssmith -password stevespass -setservername mysnazzyserver

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setservername mysnazzyserver

- 65 -

setserversettings

Use this command to set a number of server settings using a properties.txt file (see Properties Files on page 54). All undefined values in the properties file are ignored.

-setserversettings -properties pro perties.txt

The following is a list of server properties available to be set using this command:

Property esp.container.autostart

esp.core.bonjour.name

esp.core.repository.location

Description

This is the autostart setting of the server: enabled or disabled.

The Bonjour name of the server. Any alphanumeric value is acceptable.

The complete full path to the server vault.

esp.core.service.backup.directory Directory where backup files are to be written. This path must allow changes.

esp.core.service.backup.schedule

Backup schedule expression. Expression must adhere to the formats supported by Quartz.

esp.core.service.logging.level

The logging level of the server. Four case-sensitive values are acceptable: error, warn, info, or debug.

esp.core.service.logging.location Complete path to the folder where logs are to be written. This folder must allow changes.

esp.core.service.state

The current state of the server can be set to one of three case-sensitive values: started, stopped, or standby.

esp.port.admin-web-app esp.port.bootstrap-jnp

The Server Administration port, also called the Jetty Web App port. Any positive integer between 1 and 65536 inclusive.

The Bootstrap JNP Server Bind Address port. Any positive integer between 1 and 65536 inclusive.

esp.port.http

esp.port.jmx-pooled esp.port.jmx-rmi esp.port.rmi-naming esp.port.webservice

The User Management port. This port is also used for client connection and also called the JBoss HTTP / Web Service port. Any positive integer between 1 and 65536 inclusive.

The JMX Pooled Port. Any positive integer between 1 and 65536 inclusive.

The JMX RMI Object Port. Any positive integer between 1 and 65536 inclusive.

The RMI Naming Service port. Any positive integer between 1 and

65536 inclusive.

The JBoss Webservice port. Any positive integer between 1 and 65536 inclusive.

Windows usage example:

esp-admin -username ssmith -password stevespass -setserversettings -properties properties.txt

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setserversettings

-properties properties.txt

- 66 -

setstate

Use this command to change the running state of the server. The server can be started, stopped or put into standby mode with the following case-sensitive values: l started l l stopped standby

-setstate value

Windows usage example:

esp-admin -username ssmith -password stevespass -setstate stopped

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -setstate stopped

tailadminlog

This command displays the most recent activity in the extensis.admin.log file and takes no parameters. This log file is located in the Universal Type Server logs subdirectory.

-tailadminlog

Windows usage example:

esp-admin -username ssmith -password stevespass -tailadminlog

Macintosh usage example:

sudo ./esp-admin.sh -username ssmith -password stevespass -tailadminlog

- 67 -