i
This document refers to an older version. GeneXus 16 is our latest version; check the latest one here.

GAM deploy tool command line

Official Content

The purpose of the GAM deploy tool command line is to run in any platform (Windows or Unix-like), and perform all the actions that the same UI tool performs, except the creation and reorganization of the GAM database tables (which can be executed by the DBA using the reorganization scripts).

This tool allows running several types of actions, so the call (in the case of Java) must have this format:

java -cp <classpath> artech.security.api.agamdeploytool "<Action> <Corresponding Flags>"

In the case of NET:

agamdeploytool.exe "<Action> <Corresponding Flags>"

Note that the configuration files for connecting to the database must be in the current directory (client.cfg in the case of Java and client.exe.config in the case of NET). Ideally, you run this tool positioned under the deployment environment. In the case of NET, under the virtual directory\bin directory. In the case of Java, under the Webapp.

The tool doesn't ask for the GAM database connection settings (such as the server, port, user, password) because that information is taken from the configuration files mentioned before.

It's distributed together with the GAM libraries, for each corresponding DBMS.

Therefore, for Java, the .jar files shown below must be included in the classpath. These libraries are inside the deployment lib directory.

  • artech.security-mysql.jar (or the corresponding DBMS)
  • gxclassr.jar
  • GxUtils.jar
  • joda-time-2.8.2.jar
  • GAMCache.jar
  • GAMCryptography.jar
  • <JDBC driver> E.g:mysql-connector-java-5.1.11-bin.jar
  • xercesImpl.jar
  • GXzip.jar
  • commons-io-2.2.jar
     

 Tool parameters


The actions provided by the tool are as follows:

Action Description
-Initialize Initializes the GAM database with its metadata
-Import Imports a package
-UpgradeGAM Updates the GAM database version; if a reorganization is necessary, the user will have to previously perform it and then run this tool action.
-Help Shows the actions available in the tool.
-Export Exports a GAM database data and stores it in a .gpkg package.
-GetConnections Obtains the connections grouped by Repository. This function is useful to obtain the repository GUIDs and connection names that will be sent as parameters in the UpdateConnectionFile option.
-UpdateConnectionFile Updates/Creates the Connection.gam file with the connection data it obtains.
-xml_config_file This is a special flag that only receives an XML file in which all the parameters to enter in the tool are loaded, including the action. The XML format is the one given by the -GenerateXML flag.
-GenerateXML Generates a sample XML and displays it in standard output. It's a sample XML that can be used as input for the tool, changing the corresponding tag values.


For each action, different flags are expected:
 

Initialize

Flag Description
-admin_name It's the GAM admin name (for example: gamadmin)
-admin_pass It's the GAM admin password (for example: gamadmin123)
-xml_config_file  string Indicates the path to the XML file that has all the parameters configured. If this flag is sent, all the others are automatically canceled and only the file parameters are taken into account. 
-help Shows the flags expected for this action.

 

UpgradeGAM

The same as Initialize.

Import

Flag Description
-file_path_package Receives the package to import.
-admin_name It's the GAM admin name.
-admin_pass It's the GAM admin password.
-admin_user_name It's the administrator user name.
-admin_role_guid GUID of the administrator role.
-upd_rep (true/false) Indicates if an update of the existing repository is to be made.
-upd_rep_guid  Indicates the GUID of the repository to update. It is used if the flag -upd_rep = true.
-new_rep_create (true/false) Indicates if a new repository is to be created.
-new_rep_name(*) It's the name of the new repository
-new_rep_namespace It's the namespace of the new repository.
-new_rep_guid(*) It's the GUID of the new repository
-new_rep_admin_name(*) It's the name of the new repository admin
-new_rep_admin_pass(*) It's the password of the new repository admin
-new_rep_conn_usr_name(*) It's the new repository connection user  name
-new_rep_conn_usr_pass(*) It's the password of the new repository connection user
-imp_auth_types (true/false) Indicates if the authentication types are to be imported.
-imp_sec_policies (true/false) Indicates if the security policies are to be imported.
-imp_users (true/false) Indicates if the users are to be imported.
-imp_roles (true/false) Indicates if the roles are to be imported.
-imp_apps (full/none/custom)

It's the level with which the applications are imported.

  • full: all applications are imported with all permissions
  • none: nothing is imported in relation to applications
  • custom: they are configured according to -imp_apps_details
-imp_apps_details(**)

It's the list of "GUID,Boolean" pairs of (applicationsGuids,ImportPermissionsOfThatApplication) to be imported.

Format: App_Guid_1,Imp_Prms_App1;App_Guid_2,Imp_Prms_App2;App_Guid_3,Imp_Prms_App3 

-imp_connections Import the package connections. The connection name is changed to <original name> + Repository Id.
For new repositories, a new connection is always created, regardless the value of this flag.
If the repository is being updated, and -imp_connections=true, the connections are imported if they don't have the same connection user name of an existing connection. In other words, the connections are not updated.
-imp_eve_subscriptions Import the events subscriptions data. Available since GeneXus 15 upgrade 12
-verbose (true/false)  
-connection_gam_file_path  
-xml_config_file Indicates the path to the xml file that has all the parameters configured. If this flag is sent, all the others are automatically canceled and only the file parameters are taken into account. 
-help  


*flags required if flag new_rep_create = true
**flags required if imp_apps = custom

Export

Flag Description
-admin_name It's the GAM admin name.
-admin_pass It's the GAM admin password.
-target It's the target directory where the package is to be stored.
-rep_guid (*required) GUID of the repository to be exported.
-full_export (true/false) If this flag is set to true, a full export is made, as follows: All roles, users and applications.
-exp_users (true/false) Indicates if the users are to be exported (it only works if full_export  = false)
-exp_roles (true/false) Indicates if the roles are to be exported (it only works if full_export  = false)

-exp_eve_subscriptions

(true/false)

Indicates if the events subscriptions data will be exported (it only works if full_export  = false). Available since GeneXus 15 upgrade 12.
-apps It's the list of GUIDs of applications to be exported. Format: App_Guid_1,App_Guid_2,App_Guid_3
-roles It's the list of GUIDs of roles to be exported. Format: Role_Guid_1,Role_Guid_2,Role_Guid_3
-pkg_name It's the name that will be given to the exported package.
-xml_config_file Indicates the path to the xml file that has all the parameters configured. If this flag is sent, all the others are automatically canceled and only the file parameters are taken into account. The format is the same as that of the import SDT.
  

GetConnections

Flag Description
-admin_name It's the GAM admin name (for example: gamadmin)
-admin_pass It's the GAM admin password (for example: gamadmin123)
-xml_config_file    Indicates the path to the xml file that has all the parameters configured. If this flag is sent, all the others are automatically canceled and only the file parameters are taken into account.
-help Shows the flags expected for this action

 

UpdateConnectionFile

Flag Description
-admin_name It's the GAM admin name (for example: gamadmin)
-admin_pass It's the GAM admin password (for example: gamadmin123)
-target It's the target directory where the connection.gam file is to be generated.
-connections It's a list with the following format: <GuidRepoA>,<NameOfAConnectionOfRepoA>;<GuidRepoB>,<NameOfAConnectionOfRepoB>
-xml_config_file Indicates the path to the xml file that has all the parameters configured. If this flag is sent, all the others are automatically canceled and only the file parameters are taken into account. 

 

Examples of how to execute the tool

Creating a new repository

/opt/tomcatproduction/webapps/Test/WEB-INF/classes# java -cp "../lib/*" artech.security.api.agamdeploytool -import -admin_name gamadmin -admin_pass gamadmin123 -file_path_package /home/sabrina/test.gpkg -new_rep_create true -new_rep_name testrepo -new_rep_namespace testrepo -new_rep_admin_name adminnew -new_rep_admin_pass admin123 -new_rep_guid 19bd e07d-8b37-4668-8c65-4cab29d8a38c -verbose true -new_rep_conn_usr_name newconn -new_rep_conn_usr_pass newconn123 -admin_role_guid 2a984733-5308-4444-b893-473200d40eda -imp_connections true 

Exporting a repository

root@ubuntu:/opt/tomcatproduction/webapps/Test/WEB-INF/classes# java -cp "../lib/*" artech.security.api.agamdeploytool -export -target /home/sabrina -admin_name gamadmin -admin_pass gamadmin123 -full_export TRUE -pkg_name test -rep_guid 1e89a9ca-bc52-482b-a344-c4cda4a9cc8f

Availability

Since GeneXus 15 Upgrade 9

linux