Official Content

The GAM Deploy Tool command line is designed to perform various security-related operations in GeneXus applications.  It is compatible with both Windows and Unix-like operating systems.

Note that while the GAM Deploy Tool supports many functions of the UI tool, it does not handle the creation and reorganization of GAM database tables. These tasks must be managed by the DBA using dedicated reorganization scripts.

Important note

For security reasons, the GAM Deploy Tool (GDT) will no longer automatically be included in the applications. The GDT is distributed with GeneXus where it was usually distributed (<GeneXusInstallation/Library/GAM/Platforms/<Generator&DBMS>), within each platform there will be a GAMDeployTool.zip file that will contain everything necessary to run this tool independently.

Functions and actions

This tool allows running several types of actions, so the call must have this format:

JAVA: <unzip_GDT_folder>/library
java -cp ./* genexus.security.api.agamdeploytool "<Action> <Corresponding Flags>"

.NET Framework: <unzip_GDT_folder>/bin
agamdeploytool.exe "<Action> <Corresponding Flags>"

.NET: <unzip_GDT_folder>/bin
 dotnet agamdeploytool.dll "<Action> <Corresponding Flags>"

JAVA

The configuration files for connection to the database must be in the current directory (where the commands will be executed), these files are client.cfg and the application.key and must be copied to the GDT Library folder.

  • The client.cfg file it's located under: <application_server>/webapps/<your_webapp>/WEB-INF/<your_app_package>
  • The application.key file it's located under: <application_server>/webapps/<your_webapp>/WEB-INF

.NET Framework

The configuration files for connection to the database must be in the current directory (where the commands will be executed), these files are client.exe.config and application.key and must be copied to the GDT BIN folder.

  • The client.exe.config file it's located under: <application_server>/<your_virtual_directory>/bin
  • The application.key file it's located under: <application_server>/<your_virtual_directory>/bin

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

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

.NET Core

The configuration files for connection to the database must be in the current directory (where the commands will be executed), these files are client.exe.config and application.key and must be copied to the GDT BIN folder.

  • The client.exe.config file it's located under: .../<KB_Name>/<Environment>/Library/GAM
  • The application.key file it's located under: .../<KB_Name>/<Environment>/Web/bin

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

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

 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 (default: gamadmin)
-admin_pass It's the GAM admin password (default: gamadmin123)
-xml_config_file  string Indicates the path to the XML file that has all the parameters configured. If this flag is set, all the others are automatically ignored and only the file parameters are taken into account. 
-help Shows the flags expected for this action.

UpgradeGAM

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

(*)required flag.

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 (*) GUID of the repository to be exported.
-pkg_name (*) It's the name that will be given to the exported package.
-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 event subscriptions data will be exported (it only works if full_export  = false). Available since GeneXus 15 upgrade 12.
-verbose (true/false)  
-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
-xml_config_file Indicates the path to the XML file that has all the parameters configured. If this flag is set, all the others are automatically ignored and only the file parameters are taken into account. The format is the same as that of the import SDT.

(*)required flag.

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_full (true/false) Indicates that all the entities will be imported (auth_types, sec_policies, users, roles, apps, connections, eve_subscriptions). Available since GeneXus 16 upgrade 6.
-disable_upd_role_prm (true/false) Indicates whether the permissions of the roles that already exist in the Database should be imported
The default value is false.
-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 of 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 It's the target directory where the connection.gam file is to be generated.
-xml_config_file Indicates the path to the XML file that has all the parameters configured. If this flag is set, all the others are automatically ignored and only the file parameters are taken into account. 
-help  

(*) required flag.
(**) flags required if flag new_rep_create = true.
(***) flags required if imp_apps = custom.

Note: After the import of the first user repository you will need to get the connection.gam from where it was configured to be generated in the tool (-connection_gam_file_path). If you need to copy the connection.gam file to production take it from this path, and if you need to define an environment variable you must open this file (connection.gam) and copy the Key tag value in the environment variable GX_GAMCONNECTIONKEY.

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 set, all the others are automatically ignored and only the file parameters are taken into account.
-help Shows the flags expected for this action.

(*) required flag.

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 set, all the others are automatically ignored and only the file parameters are taken into account. 

(*) required flag.

Samples of how to execute the tool

The default password for gamadmin user is gamadmin123.

Initializa GAM database (JAVA)

<unzip_GDT_folder>/library> java -cp ./* genexus.security.api.agamdeploytool -initialize -admin_name gamadmin -admin_pass <your_gamadmin_pass>

Initialize GAM database (.NET)

<unzip_GDT_folder>/bin> dotnet agamdeploytool.dll -initialize -admin_name gamadmin -admin_pass <your_gamadmin_pass>

Upgrade GAM database version (.NET)

<unzip_GDT_folder>/bin> dotnet agamdeploytool.dll -upgradegam -admin_name gamadmin -admin_pass <your_gamadmin_pass>

Get connections  (.NET Framework)

<unzip_GDT_folder>/bin>> agamdeploytool.exe -getconnections -admin_name gamadmin -admin_pass <your_gamadmin_pass>

Updating connection file (.NET Framework)

<unzip_GDT_folder>/bin> agamdeploytool.exe -updateconnectionfile -admin_name gamadmin -admin_pass <your_gamadmin_pass> -target C:\Models\TestGDT\CSharpModel\web\ -connections 92b783a2-2a50-4261-8ba7-684fb780967d,GAM-Manager

Creating a new repository (JAVA)

<unzip_GDT_folder>/library># java -cp ./* genexus.security.api.agamdeploytool -import -admin_name gamadmin -admin_pass <your_gamadmin_pass> -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 (JAVA)

<unzip_GDT_folder>/library># java -cp ./* genexus.security.api.agamdeploytool -export -target /home/sabrina -admin_name gamadmin -admin_pass <your_gamadmin_pass> -full_export TRUE -pkg_name test -rep_guid 1e89a9ca-bc52-482b-a344-c4cda4a9cc8f

Important notes

  • You may need to copy the client.cfg to the classes directory if you have a package.
  • If you are getting errors of access denied when connecting to the DBMS when executing one of the tool actions, please check the following: SAC#43289.

Last update: November 2024 | © GeneXus. All rights reserved. GeneXus Powered by Globant