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 to manage sessions, GAS configuration, and manage applications and clients:

Syntax

gasadmin { -V | -h | command [ options ] [ args ] }
  1. Display help or version information for the gasadmin command. Help is specific to commands and there is a help option for each command.
  2. command. There are six commands to administer the GAS:
    1. session administers application sessions.
    2. config handles GAS configuration.
    3. gar deploys and manages Genero archives (gar) files.
    4. gbc deploys and manages Genero Browser Clients (GBC) on the GAS.
    5. reset-log reconfigures the logs for sessions running on the GAS.
    6. monitoring monitors Web service on the GAS. This command supports six commands:
      1. status gets monitoring configuration status.
      2. update sets the monitoring configuration.
      3. reset resets the monitoring configuration.
      4. fetch retrieves monitoring data stored in .dat files.
      5. clean removes monitoring data stored in .dat files.
      6. preload configures monitoring from commands stored in a file.
  3. options are specific to commands and these are described in the next paragraphs.
  4. args. Some commands have arguments and these are described in the next paragraphs.

Syntax 1: session command 

gasadmin session [options]
  1. The session command administers GAS sessions (default).
  2. options are described in Session options.

Syntax 2: config command

gasadmin config [options]
  1. The config command handles GAS configuration.
  2. options are described in Config options.

Syntax 3: gar command

gasadmin gar [options]
  1. The gar command deploys Genero archives (gar) files.
  2. options are described in gar options.

Syntax 4: gbc command

gasadmin gbc [options]
  1. The gbc command deploys Genero Browser Client (GBC).
  2. options are described in gbc options.

Syntax 5: reset-log command

gasadmin reset-log [options] { dispatcher | session_id [...] | dispatcher session_id [...] }
  1. The reset-log command reconfigures the logs for the running dispatcher and/or for one or more sessions.
  2. options are described in reset-log options.
  3. Specify the running dispatcher (using the word "dispatcher") and/or session ids. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9". One or more sessions may be specified, separated by spaces.

Syntax 6: monitoring status command

gasadmin monitoring status [options] { session-id | service-name }
  1. The monitoring status command gets monitoring configuration status.
  2. options are described in monitoring status options.
  3. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9".
  4. The service-name identifies the Web service session. If the service belongs to a group of services in the GAS, the format is group-name/service-name. For example, "demo/Calculator". If the service belongs to the default group of services in the GAS, there is no need to use the group name.

Syntax 7: monitoring update command

gasadmin monitoring update [options] { session-id | service-name }
  1. The monitoring update command sets the monitoring configuration.
  2. options are described in monitoring update options.
  3. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9".
  4. The service-name identifies the Web service session. If the service belongs to a group of services in the GAS, the format is group-name/service-name. For example, "demo/Calculator". If the service belongs to the default group of services in the GAS, there is no need to use the group name.

Syntax 8: monitoring reset command

gasadmin monitoring reset [options] { session-id | service-name }
  1. The monitoring reset command resets the monitoring configuration.
  2. options are described in monitoring reset options.
  3. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9".
  4. The service-name identifies the Web service session. If the service belongs to a group of services in the GAS, the format is group-name/service-name. For example, "demo/Calculator". If the service belongs to the default group of services in the GAS, there is no need to use the group name.

Syntax 9: monitoring fetch command

gasadmin monitoring fetch [options] session-id
  1. The monitoring fetch command retrieves monitoring data stored in .dat files.
  2. options are described in monitoring fetch options.
  3. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9".

Syntax 10: monitoring clean command

gasadmin monitoring clean [options]
  1. The monitoring clean command removes monitoring data stored in .dat files.
  2. options are described in monitoring clean options.

Syntax 11: monitoring preload command

gasadmin monitoring preload [options] command-file
  1. The monitoring preload command configures monitoring from commands stored in a file.
  2. options are described in monitoring preload options.
  3. command-file identifies the command file.

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
-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.
--whoami Display the kind of dispatcher the GAS is using: httpdispatch, fastcgidispatch, or isapidispatch. See Example: Show 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 Example: 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 Example: Close 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 Example: List sessions.

-C
--session-cleanup

 Clear remaining Linux®/UNIX™ domain sockets, and delete temporary files/directories that may not have been removed at the end of a session. See Example: Cleanup session.

-m
--monitor

 Retrieve monitor information for a session. Information is displayed in XML format on the standard output. See Example: Monitor session.
--broadcast-message message Broadcast a message to all connected user agents.
--idle-time session_id Return the number of seconds a session is in an idle state (meaning no user activity on all applications and child applications for the given session). See Example: Idle 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
-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.

-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.
--undeploy-archive archive_file Undeploy the given archive.
--enable-archive archive_file Expose all services and applications contained in the given archive.
--disable-archive archive_file Unexpose all services and applications contained in the specified archive.
--list-archives List all archives deployed on the Genero Application Server.
--clean-archives Clean up all 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.
Note:

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
-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} Log type (CONSOLE or DAILYFILE), default is DAILYFILE.
Note:

In development, with the standalone GAS (httpdispatch), the CONSOLE or DAILYFILE log can be reset. In production, with isapidisapatch and fastcgidispatch dispatchers, you can only reset 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.
Table 7. gasadmin monitoring status command options for monitoring Web services
Option Description
-h

--help

 Displays help for the command.
-q

--quiet

 Operates in silent mode
-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.
--session Monitor the status of a session.
--service Configure monitoring for a service.

While you typically include both the group and the service name using the format "--service group-name/service-name", you must not include the group when the service is in the _default services group. For services in the _default group, simply provide the service name using the format "--service service-name".
--xml-output Output result of command in XML format.
--file filename Output result of command in file
Table 8. gasadmin monitoring update command options
Option Description
-h

--help

 Displays help for the command.
-q

--quiet

 Operates in silent mode
-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.
--session Configure monitoring for a session.
--service Configure monitoring for a service.

While you typically include both the group and the service name using the format "--service group-name/service-name", you must not include the group when the service is in the _default services group. For services in the _default group, simply provide the service name using the format "--service service-name".
--enable Enable monitoring. You can enable monitoring by session id or service name using the gasadmin monitoring update --enable command. If monitoring a service (with --service option) that it is not yet deployed, the GAS notifies you of this with a message that the configuration is saved to load once the service is available.
--disable Disable monitoring.
--level { ALARM | MIN* | MEDIUM | HIGH } Set the monitoring level to one of the valid options: ALARM, MIN*, MEDIUM, or HIGH. The default is MIN.
Note:

Levels are case sensitive.
--set-alarm { alarm-name | alarm-name=threshold } Set alarm of given name and optional threshold (for example, DVM_NOT_STARTED=1)
--unset-alarm alarm-name Remove the alarm of given name.
--list-alarm List all alarm names and types.
--xml-output Output result of command in XML format.
--file filename Output result of command in file
Table 9. gasadmin monitoring reset command options
Option Description
-h

--help

 Displays help for the command.
-q

--quiet

 Operates in silent mode
-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.
--session Reset monitoring for a session.
--service Configure monitoring for a service.

While you typically include both the group and the service name using the format "--service group-name/service-name", you must not include the group when the service is in the _default services group. For services in the _default group, simply provide the service name using the format "--service service-name".
--xml-output Output result of command in XML format.
--file filename Output result of command in file
Table 10. gasadmin monitoring fetch command options
Option Description
-h

--help

 Displays help for the command.
-q

--quiet

 Operates in silent mode
-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.
--xml-output Output result of command in XML format.
--file filename Output result of monitoring fetch command to file.
Table 11. gasadmin monitoring clean command options
Option Description
-h

--help

 Displays help for the command.
-q

--quiet

 Operates in silent mode
-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.
--all Remove all monitoring data for all sessions using the --all option on its own. Or remove all data older than a given number of days using the --all --days num_days option.
Note:

session_id is not required when you specify --all.
--days num_days [ session_id ] Remove monitoring data older then given number of days starting from today for a given session id. This option can also be used with the option --all.
--file filename Output result of command in file
Table 12. gasadmin monitoring preload command options
Option Description
-h

--help

 Displays help for the command.
-q

--quiet

 Operates in silent mode
-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 { httpdispatch | fastcgidispatch | isapidispatch }

--dispatcher { httpdispatch | fastcgidispatch | isapidispatch }

 Specify the target dispatcher. This option is mandatory as the preload command must be run when the dispatcher is not running.
--force Force overwriting of existing configuration
--directory directory-name Specify the command file directory location
--file filename Output result of command in file

Session command examples

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

Example: Ping sessions

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

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 -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/gwc-demo): OK

Example: List sessions

This example shows how to list all 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 -l

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".
    Note:

    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.
Session list: (httpdispatch)
  - 96c9ce0ded72135ddf43ad421a2d87b9
    Name: demo/RestBook
    Port: 51744
    Type: WebServices
    Pid : 7708
    GSID:
    VM Pids:
      - 13880
      - 17068
  - dfd29c347ecf2d572aef95a13c6d4a04
    Name: _default/gwc-demo
    Port: 51732
    Type: UA Client
    Pid : 8632
    GSID: 1a5569ed45193a6abd7a2e8e67199300
    VM Pids:
      - 8568
      - 13880
      - 17068
      - 6448

Example: Stop sessions

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

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.

This action affects the specified session id, "d98290172c8f7c0d861db329f1ce6597" in the example. 
gasadmin session -k
          d98290172c8f7c0d861db329f1ce6597 -f as1.xcf
Tip:

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

Example: Close 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 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.

In the example the close session action affects the specified session id, "d98290172c8f7c0d861db329f1ce6597". 
gasadmin session --close-session d98290172c8f7c0d861db329f1ce6597 -f as1.xcf
Tip:

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

Example: 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.

The command is run on the admin port (TCP_ADMIN_PORT) used by the dispatcher for this purpose.
gasadmin session --session-cleanup
Note:

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>

Example: Show dispatcher

The gasadmin session --whoami option provides information 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 --whoami -f as1.xcf
The command will return the kind of dispatcher you are communicating with: httpdispatch, fastcgidispatch, or isapidispatch.

Example: Monitor session

This example shows how to use the --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 -d httpdispatch --monitor d98290172c8f7c0d861db329f1ce6597
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>

Example: Idle session

The --idle-time session option is useful if you want to check on user activity for a given session. It gives you the number of seconds since last user activity. Based on this, for example, you can decide if a session that has had no user activity for some time, can be stopped.

In the example the idle time session action affects the specified session id, "de7b246d34b550020610f40bbcebe20d". 
gasadmin session --idle-time de7b246d34b550020610f40bbcebe20d
Information on the current idle status of the session is sent to the standard output. The number of seconds (496 in the example) is the time elapsed since the last user activity.
Idle time for session de7b246d34b550020610f40bbcebe20d: 496

Deploy with gar example

The gar command deploys Genero archives (gar) files.
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

Command options are described in gar options.

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 --deploy command to deploy a GBC client on the GAS.
gasadmin gbc --deploy c:\fjs\gbc-projects\gbc-4.01.02\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
Figure: List deployed GBC and set default

Images shows the result of the gasadmin commands to list deployed GBC and to set the default client

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 example command resets logging for the specified session. It resets where the log messages are sent; the --output-type option specifies the logs be 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.

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.
Tip:

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

Example: Reset logs for dispatcher

gasadmin reset-log --output-type DAILYFILE --categories "ALL DEBUG" dispatcher

The example command resets the log messages written to the log file. The --output-type option specifies the logs be 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. These changes affect the running dispatcher.

Example: Display GAS version information

gasadmin -V