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.
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.
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>"
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
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.
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.
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:
| 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. |
| 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.
| 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.
| 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.
| 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.
| 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.
The default password for gamadmin user is gamadmin123.
<unzip_GDT_folder>/library> java -cp ./* genexus.security.api.agamdeploytool -initialize -admin_name gamadmin -admin_pass <your_gamadmin_pass>
<unzip_GDT_folder>/bin> dotnet agamdeploytool.dll -initialize -admin_name gamadmin -admin_pass <your_gamadmin_pass>
<unzip_GDT_folder>/bin> dotnet agamdeploytool.dll -upgradegam -admin_name gamadmin -admin_pass <your_gamadmin_pass>
<unzip_GDT_folder>/bin>> agamdeploytool.exe -getconnections -admin_name gamadmin -admin_pass <your_gamadmin_pass>
<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
<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
<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
- 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.