gasadmin tool

The gasadmin tool is provided as an administrative command for the Genero Application Server.

Links to examples of some of the more common uses of the tool are grouped under headings: manage sessions, manage applications and clients, manage logs, GAS configuration, and display information:

Manage sessions
Manage applications and GBC clients
- Deploying and managing applications with GAR.
- Manage GBC clients.
Manage logs
- Example: Reset logs for session.
GAS configuration
Display information
- Display GAS version information.

Syntax 1

gasadmin { -V | -h | command [options] }

Syntax 2: with commands (session, config, gar, gbc, reset-log)

gasadmin { session | config | gar | gbc | reset-log [options] }

gasadmin commands

The gasadmin tool supports five commands:

```
gasadmin session [options]
```
The session command administers GAS sessions (default). Options are described in Table 2.
```
gasadmin config [options] 
```
The config command handles GAS configuration. Options are described in Table 3.
```
gasadmin gar [options] 
```
The gar command deploys Genero archives (gar) files. Options are described in Table 4.
Important: If you start the dispatcher with the option (-E) to override the $(res.appdata.path) location, you must also override the resource when deploying applications with the gasadmin gar command, in order to deploy to the correct directory.
For example, specify the same option with both commands:
- Starting the dispatcher:
  httpdispatch -E res.appdata.path=/work/tmp/gas/appdata
- Deploying the application:
  gasadmin gar -E res.appdata.path=/work/tmp/gas/appdata --deploy-archive myapp.gar
```
gasadmin gbc [options] 
```
The gbc command deploys Genero Browser Client (GBC). Options are described in Table 5.
```
gasadmin reset-log [options ] [session-id ...]
```
The reset-log command reconfigures the logs for one or more sessions. Options are described in Table 6.

Options

Table 1. gasadmin version and help options
Option	Description
`-V` `--version`	Display the version of the GAS and details about the GAS installation.
`-h` `--help`	Displays help for the gasadmin command.

Table 2. gasadmin session command options for managing sessions
Option	Description
`-h` `--help`	Displays help for the command.
`-q` `--quiet`	Operates in silent mode. Disables logging.
`-p directory-name` `--as-directory directory-name`	Specify the Genero Application Server directory.
`-f filename` `--configuration-file filename`	Specify the configuration file to use. If not specified, the default configuration file, $FGLASDIR/etc/as.xcf, is used.
`-E resource_name=value` `--resource-overwrite resource_name=value`	Define or overwrite a resource.
`-d dispatcher-name` `--dispatcher dispatcher_name`	Target the dispatcher - used by session-related options to select the target dispatcher.
`-K` `--kill-all-sessions`	Stop (kill) all active sessions by requesting each proxy to stop. The user agent is notified with error messages.
`-k session-id` `--kill-session session_id`	Stop the specified session id . The user agent is notified with error messages. See Stop sessions.
`--close-all-sessions`	Close all active sessions. No messages are sent to the user agent. Sessions are closed gracefully.
`--close-session session_id`	Close the specified session id. No message is sent to the user agent. The session is closed gracefully. See Close dispatcher sessions.
`-X` `--ping-all-sessions`	Ping all active sessions. See Example: Ping sessions.
`-x session-id` `--ping-session session_id`	Ping the specified session id.
`-l` `--list-sessions`	List all known sessions and display details of the running applications and web services. See also the `gasadmin list-sessions`command. For examples, go to Example: List sessions.
`--list-session-ids`	List all known sessions identifiers. For examples, go to Example: List session ids.
`--count-sessions`	Return a count of the number of active sessions.
`-m session_id` `--monitor session_id`	Retrieve monitor information for a specified session. Information is displayed in XML format on the standard output. See Monitor session.

Table 3. gasadmin config command options for GAS configuration
Option	Description
`-h` `--help`	Displays help for the command.
`-q` `--quiet`	Operates in silent mode. Disables logging.
`-p directory-name` `--as-directory directory-name`	Specify the Genero Application Server directory.
`-f filename` `--configuration-file filename`	Specify the configuration file to use. If not specified, the default configuration file, $FGLASDIR/etc/as.xcf, is used.
`-E resource_name=value` `--resource-overwrite resource_name=value`	Define or overwrite a resource.
`-c` `--configuration-check`	Checks the GAS configuration file (as.xcf) and exits. Errors are displayed to the standard output. See Validating with the gasadmin tool.
`-e` `--configuration-explode`	Explode the GAS configuration into a hierarchy of configuration elements and output to file in XML format, one for each application.
`-t config_file_name` `--configuration-explode-external config_file_name`	Explode the given external configuration file in current directory. See Example: Explode configuration file into an XML file
`-r` `--configuration-expand-resources`	Expand resources and replace with real values. Used with `--configuration-explode` or `--configuration-explode-external`. See Example: Explode configuration file into XML files
`-z path[,...]` `--compress-resources path[,...]`	Compress the resources located in specified paths. The path separator is a comma (,). See Example: Compress resources.
`--list`	Lists all applications and services (not just the deployed ones) found in the GAS.
`--xml-output`	Output result in XML format (for `--list` option only).

Table 4. gasadmin gar command options for managing Genero archives (gar)
Option	Description
`-h` `--help`	Displays help for the gasadmin command.
`-p directory-name` `--as-directory directory-name`	Specify the Genero Application Server directory.
`-f filename` `--configuration-file filename`	Specify the configuration file to use. If not specified, the default configuration file, $FGLASDIR/etc/as.xcf, is used.
`-E resource_name=value` `--resource-overwrite resource_name=value`	Define or overwrite a resource.
`--deploy-archive archive_file`	Unpack the given archive content into the deployment directory. See Deploy an archive with gasadmin
`--undeploy-archive archive_file`	Undeploy the given archive. See Undeploy an archive with gasadmin
`--enable-archive archive_file`	Expose all services and applications contained in the given archive. See Enable a deployed archive with gasadmin
`--disable-archive archive_file`	Unexpose all services and applications contained in the specified archive. See Disable a deployed archive
`--list-archives archive_file[...]`	List all deployed applications in the specified archive or in the list of archives. The entries in the lists are separated by spaces. See List deployed archives
`--clean-archives archive_file[...]`	Clean up (remove) the specified archive or all the archives provided in a list of archives. The entries in the lists are separated by spaces. See Clean up undeployed archives
`--xml-output`	Output result of command in XML format. Only compatible with archive options.
`-y` `--yes`	Do not prompt for confirmation.

Table 5. gasadmin gbc command options for managing GBC
Option	Description
`-h` `--help`	Displays help for the gasadmin command.
`-p directory-name` `--as-directory directory-name`	Specify the Genero Application Server directory.
`-f filename` `--configuration-file filename`	Specify the configuration file to use. If not specified, the default configuration file, $FGLASDIR/etc/as.xcf, is used.
`-E resource_name=value` `--resource-overwrite resource_name=value`	Define or overwrite a resource.
`--deploy gbc_content`	Unpack given GBC content into the deployment directory defined by the `res.gbc.deployment` resource. See Example: Deploy GBC.
`--undeploy gbc_content`	Remove the given GBC content. If the undeployed GBC is the current default, the new default will be the one embedded in the FGLGWS package.
`--default gbc_client`	Set the specified GBC as default client. See Example: Listing GBC clients and setting a default
`--list`	List all static GBC ( those configured in the as.xcf) and deployed clients on the Genero Application Server.
`--reset`	Reset to initial delivered GBC in the FGLGWS package.
`--rename old_gbc_name=new_gbc_name`	Rename the given GBC. Important: The GBC client set as default, can not be renamed as it may be in use.
`--xml-output`	Output result of command in XML format.

Table 6. gasadmin reset-log command options for managing log output
Option	Description
`-h` `--help`	Displays help for the command.
`-q` `--quiet`	Operates in silent mode. Disables logging.
`-p directory-name` `--as-directory directory-name`	Specify the Genero Application Server directory.
`-f filename` `--configuration-file filename`	Specify the configuration file to use. If not specified, the default configuration file, $FGLASDIR/etc/as.xcf, is used.
`-E resource_name=value` `--resource-overwrite resource_name=value`	Define or overwrite a resource.
`--output-type { CONSOLE \| DAILYFILE}`	Define where logs are sent (`CONSOLE` or `DAILYFILE`), default is `DAILYFILE`. In development, with the standalone GAS (httpdispatch), you can reset log output to the `CONSOLE` or `DAILYFILE`. In production, with isapidisapatch and fastcgidispatch dispatchers, you can only reset output to the `DAILYFILE` log. See Reset-log command examples.
`--output-path output_dir`	Define the output directory where the `DAILYFILE` log file is stored. If you do not specify an output directory, gasadmin uses the value defined in the `LOG` configuration from the as.xcf.
`--raw-data-max-length max`	Define the max length of a log message. See RAW_DATA. If you do not specify the data max length, gasadmin uses the value defined in the `LOG` configuration from the as.xcf.
`--format column-headings`	Define the columns to output as the format of the log message. See FORMAT. If you do not specify the column headings, gasadmin uses the values defined in the `LOG` configuration from the as.xcf.
`--categories category-list`	Define the log categories to enable. See CATEGORIES_FILTER. If you do not specify the log categories, gasadmin uses the values defined in the `LOG` configuration from the as.xcf. See Reset-log command examples.

Session command examples

These examples show how you use the gasadmin command to work with sessions.

Example: List sessions

This example shows how to list all sessions running on the dispatcher.

gasadmin list-sessions

The output displays a list of the sessions. It includes the following details:

session identifier: identifies the GAS session for the application or web service. In the example, this is "96c9ce0ded72135ddf43ad421a2d87b9".
Name: represents the name of the application or web service running in the session.
Port: represents the port number the uaproxy or gwsproxy is using to communicate with the dispatcher (if UNIX® sockets are used, the value is 0).
Type: identifies the type of session: "WebServices" or "UA Client" (application).
Pid: represents the pid of the uaproxy or gwsproxy.
GSID: represents the Genero session id used by web applications. In the example, this is "1a5569ed45193a6abd7a2e8e67199300". The GSID is used by the browser to keep track of the session of a web application. The value is stored in a cookie. GSID is not used by web services.
VM Pids: represents the fglrun processes the current uaproxy or gwsproxy has started.

In the sample, the list is output as text. This is the default. To output in JSON format, use the gasadmin list-sessions --output json command.

Session list: (httpdispatch)
  - 96c9ce0ded72135ddf43ad421a2d87b9
    Name: demo/RestBook
    Port: 51744
    Type: WebServices
    Pid : 7708
    GSID:
    VM Pids:
      - 13880
      - 17068
  - dfd29c347ecf2d572aef95a13c6d4a04
    Name: _default/demo
    Port: 51732
    Type: UA Client
    Pid : 8632
    GSID: 1a5569ed45193a6abd7a2e8e67199300
    VM Pids:
      - 8568
      - 13880
      - 17068
      - 6448

Example: List session ids

This example shows how to list just the identifiers of the sessions running on the dispatcher.

The command is run on the admin port (TCP_ADMIN_PORT) used by the dispatcher for this purpose. With the option -f you can specify the configuration file where the port is set; otherwise, the default GAS configuration file is used.

gasadmin session list-session-ids

In the sample, the list is output as text.

    Session list:
      - 784f51e41e5010db8bc201915fc95fe8
      - 906d0e5fc69b196f348fd85d371315cf
      - 1d5d88ddf6e2cbfdcd47791583e2c163
      - 03d7e82913d590a316fbeb4b1ded6624

In this example, the command is run in silent mode.

gasadmin session list-session-ids --quiet

Just the list of session ids is output.

784f51e41e5010db8bc201915fc95fe8
906d0e5fc69b196f348fd85d371315cf
1d5d88ddf6e2cbfdcd47791583e2c163
03d7e82913d590a316fbeb4b1ded6624

Example: Ping sessions

This example shows how to use -X -f options to ping all sessions of a specified GAS configuration file.

gasadmin session -X -f as1.xcf

The GAS outputs the reply from all current sessions. The output displays the session id, which is a long string, for example, "96c9ce0ded72135ddf43ad421a2d87b9" with the name of the service or application in parenthesis. If the ping is successful, the reply from the dispatcher is OK.

Checking all sessions: (httpdispatch) Ping session
96c9ce0ded72135ddf43ad421a2d87b9 (demo/RestBook): OK Ping session dfd29c347ecf2d572aef95a13c6d4a04
          (_default/demo): OK

Stop sessions

If you need to stop a session, you use the -k option of the gasadmin session command for this purpose.

This action affects the specified session id, "d98290172c8f7c0d861db329f1ce6597" in the example. With the option -f you can specify the configuration file. The -d option you specify the dispatcher where the session is running.

gasadmin session -k d98290172c8f7c0d861db329f1ce6597 -f as1.xcf -d isapidispatch

Tip: You can use the -K option to terminate (kill) all active sessions.

Close dispatcher sessions

If you need to stop a session gracefully and therefore not send messages to the user agent, use the close session option instead of the -k (kill) option. The --close-session option runs the gasadmin command on the TCP_ADMIN_PORT port for this purpose.

In the example the close session action effects the specified session id, "d98290172c8f7c0d861db329f1ce6597". With the option -f you can specify the configuration file. The -d option specifies the dispatcher where the session is running.

gasadmin session --close-session d98290172c8f7c0d861db329f1ce6597 -f as1.xcf -d isapidispatch

Tip: You can use the --close-all-sessions option to close all active sessions on the dispatcher.

Cleanup session

This example shows you how to perform a cleanup on the GAS to remove temporary files or directories that may have been used during a session.

gasadmin session --cleanup-session -d <dispatcher>

The -d or --dispatcher option is required to specify the dispatcher. The dispatcher is specified as either httpdispatch, isapidispatch, or fastcgidispatch. This cleanup is performed automatically at dispatcher start up.

If your GAS version is prior to 3.10, you need to use the following command:

gasadmin --session-cleanup -d <dispatcher>

Monitor session

This example shows how to use the gasadmin session --monitor option to retrieve information to monitor a specified session. Information on the current status of the dispatcher is sent to the standard output in XML format during the session.

gasadmin session --dispatcher <dispatcher> --monitor <session-id>

The -d or --dispatcher option is required to specify the dispatcher.

If your GAS version is prior to 3.10, you need to use the following command:

gasadmin --dispatcher <dispatcher> --monitor <session-id>

Config command examples

These examples show how you use the gasadmin config command to work with configuration files.

Example: Explode configuration file into an XML file

This example shows how you use the -t option of the gasadmin config command to explode the specified application configuration file and expand its resources and its parent's resources into an XML file.

gasadmin config -t demo/Card

Example: Explode configuration file into XML files

This example shows how you use the -r -t options to explode the specified application configuration file. This causes its resources and its parent resources to be replaced with real values. The result is output in separate XML files.

gasadmin config -r -t demo/Card

Example: Compress resources

This example shows how you compress the resources located in the specified paths.

gasadmin config -z
            $FGLASDIR/app,$FGLASDIR/services,$FGLASDIR/web,$$FGLASDIR/tpl

GBC command examples

These examples show how you use the gasadmin gbc command to manage GBC clients.

Example: Deploy GBC

This example uses the gasadmin gbc --deploy command to deploy a GBC client on the GAS.

gasadmin gbc --deploy c:\fjs\gbc-projects\gbc-1.00.53\archive\custA.zip

Example: Listing GBC clients and setting a default

These examples show how you can use gasadmin gbc command options to list the deployed GBC clients and set a default client on the GAS.

gasadmin gbc --list

gasadmin gbc --default custB

Image shows the result of the gasadmin commands to list deployed GBC and to set the default client — Figure: List deployed GBC and set default

Reset-log command examples

These examples shows how you can use the gasadmin reset-log command to reconfigure the log output.

Example: Reset logs for session

gasadmin reset-log --output-type DAILYFILE --categories "ALL DEBUG" 1170f560ca4d03fd3aa4bbac75da97e9

The command resets logging for the specified session:

The --output-type option specifies the logs are sent to the daily log file.
The --categories option specifies the type of log messages to send; see CATEGORIES_FILTER to view the log type options.

The changes from this command only affect the specified session.

Tip:

You can specify multiple sessions by listing the session ids, separated by spaces.

For options not specified, such as --output-path, gasadmin tries to use the LOG configuration from the as.xcf. If not found in the as.xcf (for example, CONSOLE may not be configured in as.xcf), default values are used.

Display GAS version information

gasadmin -V

Image shows GAS version and build information displayed when the gasadmin -V command is run — Figure: Sample GAS Version Information