gasadmin tool

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

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 various 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.
    7. send-message allows an administrator of the GAS to send messages to connected users on the specified applications and sessions, or to connected user on all sessions running in the GAS.
    8. list-sessions lists the active sessions.
    9. close-session closes the specified sessions gracefully.
    10. close-all-sessions closes all active sessions gracefully.
  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.

Syntax 12: send-message command

gasadmin send-message [options][ session-id [,...]  | application-name [,...] ] message
  1. The send-message command allows an administrator of the GAS to send messages to connected users on the specified applications and sessions, or to connected user on all sessions running in the GAS.
  2. options are described in Table 13.
  3. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9".
  4. The application-name identifies the application. If the application belongs to a group of applications in the GAS, the format is group-name/application-name. For example, "mygroup/myapp". If the application belongs to the default group of applications in the GAS, there is no need to use the group name.
  5. message is the message you want to send to the user-agent,for example, "The server will be shutting down in 10 minutes." For examples using send-message, see Send administrative messages to user agents.

Syntax 13: list-sessions command

gasadmin list-sessions [options]
  1. The list-sessions command lists the active sessions.
  2. options are described in Table 14.

Syntax 14: close-session command

gasadmin close-session [options][ session-id [,...]  | application-name [,...] ]
  1. The close-session command closes the specified applications and sessions gracefully.
  2. options are described in Table 15.
  3. The session-id is a string that identifies the session, for example "96c9ce0ded72135ddf43ad421a2d87b9".
  4. The application-name identifies the application. If the application belongs to a group of applications in the GAS, the format is group-name/application-name. For example, "mygroup/myapp". If the application belongs to the default group of applications in the GAS, there is no need to use the group name.

Syntax 15: close-all-sessions command

gasadmin close-all-sessions [options]
  1. The close-all-sessions command closes all sessions gracefully.
  2. options are described in Table 16.

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. For examples, go to Override configuration resources
--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 The gasadmin session --close-all-sessions feature is deprecated. Use the gasadmin close-all-session command instead to close all active sessions.
--close-session session_id The gasadmin session --close-session feature is deprecated. Use the gasadmin close-session command instead to close the specified 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.

-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 session_id
--monitor session_id

Retrieve monitor information for a specified session. Information is displayed in XML format on the standard output. See Example: Monitor session.
--broadcast-message message The broadcast-message feature is deprecated. It now displays a message to use the gasadmin send-message command instead, and it exits with a status code of 1.
--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. 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. For examples, go to Override configuration resources

-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. For examples, go to Override configuration resources
--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. For examples, go to Override configuration resources
--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. For examples, go to Override configuration resources
--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.

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. 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. For examples, go to Override configuration resources
--session Monitor the status of a specified session. See Quick start: setting monitoring alarms.
--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".

See Enable and disable web service monitoring.
--xml-output Output result of command in XML format.
--file filename Output result of command in the specified file.
Table 8. gasadmin monitoring update command options
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. For examples, go to Override configuration resources
--session Configure monitoring for a session. See Quick start: setting monitoring alarms.
--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".

See Enable and disable web service monitoring.
--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. See Enable and disable web service monitoring.
--disable Disable monitoring. See Enable and disable web service 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.

Levels are case sensitive.

See Change the monitoring level for a session or service.
--set-alarm { alarm-name | alarm-name=threshold } Set alarm of given name and optional threshold (for example, DVM_NOT_STARTED=1)

See Configure alarms.

--unset-alarm alarm-name Remove the alarm of given name. See Unset alarms.
--list-alarm List all alarm names and types. See Configure alarms.
--xml-output Output result of command in XML format.
--file filename Output result of command in the specified file.
Table 9. gasadmin monitoring reset command options
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. For examples, go to Override configuration resources
--session Reset monitoring for a session. See Reset monitoring
--service Reset 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".

See Reset monitoring
--xml-output Output result of command in XML format.
--file filename Output result of command in the specified file.
Table 10. gasadmin monitoring fetch command options
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. For examples, go to Override configuration resources
--xml-output Output result of command in XML format.
--file filename Output result of monitoring fetch command to file. See Fetch monitoring data.
Table 11. gasadmin monitoring clean command options
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. For examples, go to Override configuration resources
--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.

session_id is not required when you specify --all. See Remove monitoring data.

--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. See Remove monitoring data.
--file filename Output result of command in the specified file.
Table 12. gasadmin monitoring preload command options
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. For examples, go to Override configuration resources
-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. See Configure monitoring with commands file.
--force Force overwriting of existing configuration.
--directory directory-name Specify the command file directory location.
--file filename Output result of command in the specified file.
Table 13. gasadmin send-message command options
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. For examples, go to Override configuration resources

-s session_id[,...]
--session session_id[,...]              

The -s option may be used to send a message to connected users on the specified sessions. This option can take a comma-separated list of sessions. For examples using send-message, see Send administrative messages to user agents.

-a app_name [,...]
--app app_name [,...]              

The -a option may be used to send a message to connected users on sessions of the specified applications. This option can take a comma-separated list of applications. For examples using send-message, see Send administrative messages to user agents.
Table 14. gasadmin list-sessions command options
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.
-o { json | text }

--output { json | text }

Set the output format to one of the valid options, json or text. Default is text. For examples, go to Example: List sessions
-q

--quiet

Operates in silent mode. Disables logging.

-E resource_name=value
--resource-overwrite resource_name=value              

Define or overwrite a resource. For examples, go to Override configuration resources
Table 15. gasadmin close-session command options
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. For examples, go to Override configuration resources

-s session_id[,...]
--session session_id[,...]              

The -s option may be used to close the specified sessions. This option can take a comma-separated list of sessions. See Example: Close sessions.

-a app_name[,...]
--app app_name[,...]              

The -a option may be used to close sessions of the specified applications. This option can take a comma-separated list of applications. See Example: Close sessions.

-m msg
--message msg              

The -m option may be used to forward a message for display to all user agents on closing the session. The message must be enclosed in quotes. For examples, see Example: Close sessions.
Warning:

Options -m and -u are mutually exclusive.

-u url
--end-url url              

The -u option may be used to forward an URL for redirection by all user agents on closing the session. The URL must be enclosed in quotes. For examples, see Example: Close sessions.
Warning:

Options -m and -u are mutually exclusive.

Table 16. gasadmin close-all-sessions command options
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. For examples, go to Override configuration resources

-m msg
--message msg              

The -m option may be used to forward a message for display to all user agents on closing the session. The message must be enclosed in quotes. For examples, see Example: Close sessions.
Warning:

Options -m and -u are mutually exclusive.

-u url
--end-url url              

The -u option may be used to forward an URL for redirection by all user agents on closing the session. The URL must be enclosed in quotes. For examples, see Example: Close sessions.
Warning:

Options -m and -u are mutually exclusive.

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.

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

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: 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, use the gasadmin close-session to close a specified session or the gasadmin close-all-sessions to close all sessions.

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 following examples the close session action affects the specified session id, "d98290172c8f7c0d861db329f1ce6597". To get the session id, run the gasadmin session --list command.

You have the option of sending a message or an end URL to the user agents. If an end URL is specified, the user agents redirect to it on closing the session. The --message and --end-url options are mutually exclusive.
  • In this command a message is sent to display in the user agent on closing the session. The message will be displayed in the application ended page. The output shown in Figure 1 is intended as a sample to show the message displayed in the application ended page; the format may change in future product releases.
    gasadmin close-session --session d98290172c8f7c0d861db329f1ce6597 -f as1.xcf 
                                    --message "closed"
    Figure: Application ended page with message


  • In this command a URL for redirection is sent to user agents on closing the session.
    gasadmin close-session --session d98290172c8f7c0d861db329f1ce6597 -f as1.xcf 
                                    --end-url "http://www.4js.com"

In the next examples the close session action affects the specified applications:

  • In this command a message is sent to display in the user agent on closing the application session.
    gasadmin close-session --app mygroup/myapp -m "You have been disconnected"
  • In this connand a URL for redirection is sent to user agents on closing the application session.
    gasadmin close-session --app mygroup/myapp -u "http://www.4js.com"

In the next examples the close-all-sessions action affects all sessions:

  • In this command a message is sent to display in the user agent on closing all session.
    gasadmin close-all-sessions -m "You have been disconnected"
  • In this command a URL for redirection is sent to user agents on closing all sessions.
    gasadmin close-all-sessions -u "http://www.4js.com"

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
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 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 --monitor d98290172c8f7c0d861db329f1ce6597

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 gasadmin session --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 in seconds 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 gbc --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

Image 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 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.

Example: Reset logs for dispatcher

gasadmin reset-log --output-type DAILYFILE --categories "ALL DEBUG" dispatcher
The command resets logging for the running dispatcher:
  • 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.
These changes affect the running dispatcher.

Example: Display GAS version information

gasadmin -V