Calling the wladm program

You can use the wladm program to administer MobileFirst applications.

Syntax

Call the wladm program as follows:

wladm --url= --user= ... [--passwordfile=...] [--secure=false] some command

The wladm program has the following options:

Table 1. wladm program options
Option	Type	Description	Required	Default
--url	URL	Base URL of the MobileFirst web application for administration services	Yes
--secure	Boolean	Whether to avoid operations with security risks	No	true
--user	name	User name for accessing the MobileFirst admin services	Yes
--passwordfile	file	File containing the password for the user	No
--timeout	Number	Timeout for the entire REST service access, in seconds	No
--connect-timeout	Number	Timeout for establishing a network connection, in seconds	No
--socket-timeout	Number	Timeout for detecting the loss of a network connection, in seconds	No
--connection-request-timeout	Number	Timeout for obtaining an entry from a connection request pool, in seconds	No
--verbose		Detailed output	No

url

The URL preferably uses the HTTPS protocol. For example, if you use default ports and context roots, use this URL:

For WebSphere® Application Server: https://server:9443/wladmin
For Tomcat: https://server:8443/wladmin

secure

The --secure option is set to true by default. Setting it to --secure=false might have the following effects:

The user and password might be transmitted in an unsecured way (possibly even through unencrypted HTTP).
The server's SSL certificates are accepted even if self-signed or if they were created for a different host name from the server's host name.

password

Specify the password in a separate file that you pass in the --passwordfile option. In interactive mode (see Interactive mode), you can alternatively specify the password interactively. The password is sensitive information and therefore needs to be protected. You must prevent other users on the same computer from knowing these passwords. To secure the password, before you enter the password into a file, you must remove the read permissions of the file for users other than yourself. For example, you can use one of the following commands:

On UNIX: chmod 600 adminpassword.txt
On Windows: cacls adminpassword.txt /P Administrators:F %USERDOMAIN%\%USERNAME%:F

For this reason, do not pass the password to a process through a command-line argument. On many operating systems, other users can inspect the command-line arguments of your processes.

The wladm calls contains a command. The following commands are supported.

Table 2. wladm invocation supported commands
Command	Description
`show info`	Shows user and configuration information
`show versions`	Shows version information
`list runtimes [--in-database]`	Lists the runtimes
`show runtime [runtime-name]`	Shows information about a runtime
`delete runtime [runtime-name] condition`	Deletes a runtime
`list adapters [runtime-name]`	Lists the adapters
`deploy adapter [runtime-name] file`	Deploys an adapter
`show adapter [runtime-name] adapter-name`	Shows information about an adapter
`delete adapter [runtime-name] adapter-name`	Deletes an adapter
`adapter [runtime-name] adapter-name get binary [> tofile]`	Get the binary data of an adapter
`list apps [runtime-name]`	Lists the apps
`deploy app [runtime-name] file`	Deploys an app
`show app [runtime-name] app-name`	Shows information about an app
`delete app [runtime-name] app-name`	Deletes an app
`delete app version [runtime-name] app-name environment version`	Deletes a version of an app
`app version [runtime-name] app-name environment version get binary [> tofile]`	Gets the binary data of an app version
`app version [runtime-name] app-name environment version get accessrule`	Gets the access rule of an app version
`app version [runtime-name] app-name environment version set accessrule file`	Changes the access rule of an app version
`app version [runtime-name] app-name environment version get authenticitycheckrule`	Gets the authenticity check rule of an app version
`app version [runtime-name] app-name environment version set authenticitycheckrule action`	Changes the authenticity check rule of an app version
`app version [runtime-name] app-name environment version get lock`	Gets the lock state of an app version
`app version [runtime-name] app-name environment version set lock lock`	Changes the lock state of an app version
`list beacons [uuid [major minor]]`	Lists the beacons
`set beacon file`	Specifies information about a beacon
`show beacon uuid major minor`	Shows information about a beacon
`remove beacon uuid major minor`	Removes information about a beacon
`list beacon-triggers [runtime-name]`	Lists the beacon triggers
`set beacon-trigger [runtime-name] file`	Specifies a beacon trigger
`show beacon-trigger [runtime-name] trigger-name`	Shows a beacon trigger
`delete beacon-trigger [runtime-name] trigger-name`	Deletes a beacon trigger
`list beacon-trigger-associations [runtime-name] app-name [uuid major minor] [trigger-name]`	Lists the associations between beacons and beacon triggers
`set beacon-trigger-association [runtime-name] app-name uuid major minor trigger-name`	Specifies an association between a beacon and a beacon trigger
`show beacon-trigger-association [runtime-name] app-name uuid major minor trigger-name`	Shows the association between a beacon and a beacon trigger
`delete beacon-trigger-association [runtime-name] app-name uuid major minor trigger-name`	Deletes the association between a beacon and a beacon trigger
`list devices [runtime-name] [--query query]`	Lists the devices
`remove device [runtime-name] id`	Removes a device
`device [runtime-name] id set status new-status`	Changes the status of a device
`device [runtime-name] id set appstatus app-name new-status`	Changes the status of a device for an app

Interactive mode

Alternatively, you can also call wladm without any command in the command line. You can then enter commands interactively, one per line.

The exit command, or end-of-file on standard input (Ctrl-D on UNIX terminals) terminates wladm.

Help commands are also available in this mode. For example:

help
help show versions
help device
help device set status

Command history in interactive mode

On some operating systems, the interactive wladm command remembers the command history. With the command history, you can select a previous command, using the arrow-up and arrow-down keys, edit it, and execute it.

On Linux, the command history is enabled in terminal emulator windows if the rlwrap package is installed and found in PATH. To install the rlwrap package:
- On Red Hat Linux: sudo yum install rlwrap
- On SUSE Linux: sudo zypper install rlwrap
- On Ubuntu: sudo apt-get install rlwrap
On OS X, the command history is enabled in the Terminal program if the rlwrap package is installed and found in PATH. To install the rlwrap package:
1. Install MacPorts by using the installer from www.macports.org.
2. Run the command:
  sudo /opt/local/bin/port install rlwrap
  
  Then, to make the rlwrap program available in PATH, use this command in a Bourne-compatible shell:
  
  PATH=/opt/local/bin:$PATH
On Windows, the command history is enabled in cmd.exe console windows.

In environments where rlwrap does not work or is not required, you can disable its use through the option --no-readline.

The configuration file

You can also store the options in a configuration file, instead of passing them on the command line at every call. When a configuration file is present and the option –configfile=file is specified, you can omit the following options:

--url=URL
--secure=boolean
--user=name
--passwordfile=file
--timeout=seconds
--connect-timeout=seconds
--socket-timeout=seconds
--connection-request-timeout=seconds
runtime-name

Use these commands to store these values in the configuration file.

Table 3. Commands to store values in the configuration file
Command	Comment
`wladm [--configfile=file] config url URL`
`wladm [--configfile=file] config secure boolean`
`wladm [--configfile=file] config user name`
`wladm [--configfile=file] config password`	Prompts for the password.
`wladm [--configfile=file] config timeout seconds`
`wladm [--configfile=file] config connect-timeout seconds`
`wladm [--configfile=file] config socket-timeout seconds`
`wladm [--configfile=file] config connection-request-timeout seconds`
`wladm [--configfile=file] config runtime runtime-name`

Use this command to list the values that are stored in the configuration file: wladm [--configfile=file] config

The configuration file is a text file, in the encoding of the current locale, in Java™ .properties syntax. The default configuration file is on

UNIX: $HOME/.wladm.config
Windows: My Documents\IBM MobileFirst Platform Server Data\wladm.config, or My Documents\IBM Worklight Server Data\wladm.config

Note: When you do not specify a --configfile option, the default configuration file is used only in interactive mode and in config commands. For noninteractive use of the other commands, you must explicitly designate the configuration file if you want to use one.

Important: The password is stored in an obfuscated format that hides the password from an occasional glimpse. However, this obfuscation provides no security.

Generic options

There are also the usual generic options:

Table 4. Generic options
Option	Description
`--help`	Shows some usage help
`--version`	Shows the version

XML format

The commands that receive an XML response from the server verify that this response complies with the specific schema. You can disable this check by specifying --xmlvalidation=none.

Output character set

Normal output that is produced by the wladm program is encoded in the encoding format of the current locale. On Windows, this encoding format is "ANSI code page". The effects are as follows:

Characters outside of this character set are converted to question marks when they are output.
When the output goes to a Windows command prompt window (cmd.exe), non-ASCII characters are incorrectly displayed because such windows assume characters to be encoded in "OEM code page".

To work around this limitation:

On operating systems other than Windows, use a locale whose encoding is UTF-8. This format is the default locale on Red Hat Linux and OS X. Many other operating systems have a en_US.UTF-8 locale.
Or use the wladm Ant task, with attribute output="some file name" to redirect the output of a command to a file.