This appendix provides information about the Oracle Communications Mobile Synchronization Gateway command-line utilities.
You use the mgadmin command to administer Mobile Synchronization Gateway. The mgadmin command is installed in the MobileSyncGateway_home/sbin directory with user or group bin/bin permissions.
Note:
The mgadmin command administers aspects of the server and does not affect any LDAP entries.The mgadmin command requires you to authenticate with a user name and password to be able to communicate with the server. You can use the mgadmin passfile operation to store the necessary passwords in an encrypted wallet for use by subsequent mgadmin commands. If you do not store passwords in the wallet, then you must enter them by using a no-echo prompt on the command line. See "passfile Operation" for more information on how to create a file to store passwords.
Table A-1 shows the environment variable that you can use with the various mgadmin commands.
Use the mgadmin utility to administer Mobile Synchronization Gateway.
mgadmin [operation] [action]] [option1] [option2] ...
where:
operation is the mgadmin operation to run. See "mgadmin Operations" for more information.
action is the action that the specified operation performs, such as create, delete, list, and modify. Specifying an action is optional for certain operations.
option is one or more command-line options that identify information that the operation needs and the specifics of what the operation does. For example, some options provide connection parameters, and the -o option specifies a configuration parameter that the config operation can list or modify. All options are optional if the clifile is used and accessed through the environment variable MGADMIN_CLIFILE.
You can abbreviate an operation, an action, or both if they are unique in the command. For example, for the command mgadmin config list, you can enter mgadmin c l.
The default action for most commands is list. The default is used when you do not specify the action. For example, the following command lists the value of the base.ldapinfo.cachesize configuration parameter.
mgadmin config -o base.ldapinfo.cachesize
You can provide options to the mgadmin command by:
Using the command line
Using the clifile
Including them in the mgadmin.properties file
Any user can create a clifile. Only the administrative user can use the mgadmin.properties file. The mgadmin.properties file is installed in the MobileSyncGateway_home/config directory.
When you run the mgadmin command, any option that you include on the command line takes precedence over the same option in the clifile or the mgadmin.properties file. Use of the clifile or the mgadmin.properties file is mutually exclusive. If you use the clifile, use it for any option that is not on the command line. If you run the mgadmin command as the administrative user and do not supply a clifile, the mgadmin.properties file is used for any option that is not on the command line.
The mgadmin.properties file contains values for the userid, hostname, port, and secure properties based on what you input during the initial configuration.
Table A-2 shows the properties you can specify in the bootstrap file (clifile):
| Property | Description |
|---|---|
|
userid |
Specifies the Oracle GlassFish Administrator user ID. |
|
usepasswordfile |
Specifies whether to use the password file. Use y, yes, or true to use the password file. Use n, no, false, or an empty string to suppress use of the password file. |
|
hostname |
Specifies the GlassFish Server host name. |
|
port |
Specifies the GlassFish administration port (JMX port). |
|
secure |
Specifies the path to the truststore file used for a secure connection (HTTPS). |
Table A-3 shows the options that are common to all mgadmin operations.
| Short Option | Long Option | Description |
|---|---|---|
|
-u |
--userid |
Required. Specifies the GlassFish Server administrator user ID. |
|
-W |
--usepasswordfile |
Indicates to the mgadmin command to use the password file, if available. |
|
-F |
--clifile |
Specifies the path to the file containing bootstrap information. |
|
-H |
--hostname |
Specifies the server's host name. The default is localhost. |
|
-p |
--port |
Specifies the server's administrative port number. |
|
-s |
--secure |
Specifies the path and name of the trustStore file for a secure connection (HTTPS). |
|
-h |
--help |
Displays help. |
|
-V |
--version |
Lists the version of the mgadmin utility. (Checks the local package version on the disk, which can be different than what has been deployed to GlassFish Server. Version differences can occur, for example, if you added a patch but you have not yet run the init-config command.) |
Each operation also has its own specific options, as shown in the following sections.
Table A-4 describes the mgadmin operations.
| Operation | Description |
|---|---|
|
config |
Performs configuration operations, such as display the value of a particular option, set a particular option, or list all options. Some configuration operations require you to restart Mobile Synchronization Gateway. The mgadmin config modify command informs you if the change requires a server restart to take effect. |
|
passfile |
Creates, deletes, lists, or modifies passwords in the wallet. |
|
version |
Displays the product version. Mobile Synchronization Gateway Server is queried for its version. |
Each operation takes various command-line options. Table A-3, "Common Options" describes the common options used by all mgadmin operations.
Note:
Any option value that contains special characters or spaces must be enclosed in quotes ("") so that it is passed "as is" to the mgadmin command. For example:
mgadmin config modify -o base.ldapinfo.ugldap.binddn -v "cn=Directory Manager"
Use this command to list or modify Mobile Synchronization Gateway configuration parameters. See Appendix B, "Mobile Synchronization Gateway Configuration Files and Parameters" for the complete list of configuration parameters.
mgadmin config [list|modify] [-u id] [-W] [-F clifile] [-H hostname] [-p port] [-s path] [-o property] [-v value] [-d] [-f file] [-e] [-q] [-h] [-M]
Table A-5 describes the actions for the config operation.
Table A-5 Actions for config Operation
| Action | Description |
|---|---|
|
list |
Lists all configuration settings. This is the default action if not included on the command line. |
|
modify |
Modifies a configuration setting. |
At least one of the options in Table A-6 must be provided, unless you are displaying usage by using the -h option.
Table A-6 describes the options for the config operation.
Table A-6 Options for config Operation
| Short Option | Long Option | Description |
|---|---|---|
|
-o |
--option |
Specifies the configuration parameter name. Displays the configuration parameter's value if specified without the -v option. Sets the configuration parameter's value if specified with the modify action and the -v option. |
|
-v |
--value |
Specifies the value that you want to set for the configuration parameter identified by the -o option. |
|
-f |
--file |
Specifies the local file that contains the configuration option=value entries to set. Pay attention to backslashes included in this input file. Backslashes are treated as an escape character for the next character in the line. For a single backslash to be properly interpreted in a string, you must precede each backslash with another backslash. That is, use an additional backslash. For example, to include the string "aaa\bbb", you would use "aaa\\bbb". This is due to the way that Java reads in properties files. For more information, see the load(Reader reader) method of the java.util.Properties class at: |
|
-M |
--modonly |
Lists all of the configuration parameters that have been modified (that is, that contain nondefault values). |
|
-d |
--default |
Sets the value of a configuration parameter to the default when used with the modify action. Lists the default value when used with the list action. |
|
-q |
--quiet |
Suppresses output of information messages, such as "A server restart is required." |
|
-h |
--help |
Shows description of config option if specified with -o. Otherwise, shows the usage of mgadmin config. |
To show all configuration parameters:
mgadmin config list (or, because list is the default option) mgadmin config
To show the current setting for the error log:
mgadmin config -o log.mg.errors.loglevel
To set the error log to accept "finest" messages:
mgadmin config modify -o log.mg.errors.loglevel -v FINEST
To list the default setting of the base.ldapinfo.authldap.ldaptimeout parameter:
mgadmin config list -o base.ldapinfo.authldap.ldaptimeout -d -u admin Enter Admin password: base.ldapinfo.authldap.ldaptimeout: 60
To set the base.ldapinfo.authldap.ldaptimeout parameter back to its default setting:
mgadmin config modify -o base.ldapinfo.authldap.ldaptimeout -d -u admin
Use this command to create, delete, list, or modify the password file for Mobile Synchronization Gateway.
When running the mgadmin command, instead of having to enter passwords at the no-echo prompt, you can supply passwords by using the password file. The password file is an encrypted "wallet," which holds all passwords that mgadmin might use. The mgadmin passfile operation creates, deletes, or modifies this password file.
mgadmin passfile [ create | delete | list | modify ] [-u id] [-W] [-F clifile] [-H hostname] [-p port] [-s path] [-h]
Table A-7 describes the actions for the passfile operation. The default action is list. The passfile operation takes no specific options.
Table A-7 Actions for passfile Operation
| Action | Description |
|---|---|
|
create |
Creates the password file. If it already exists, modifies it. |
|
delete |
Deletes passwords in the password file. For each password, you are asked if it should be removed. |
|
list |
Displays all passwords in the password file. |
|
modify |
Modifies passwords in the password file. |
To modify the migration administrative password:
mgadmin passfile modify
Enter the Password File password:
Do you want to set the app server admin user password (y/n)? [n] y
Enter the app server admin user password:
Reenter the app server admin user password:
To list all the passwords:
mgadmin passfile list
Enter the Password File password:
The app server admin user password: password