External S-TAP deployment scripts

Before you can run a Guardium® External S-TAP container on your system, you need to prepare and run one or two deployment scripts.

Preparing to deploy an External S-TAP

At this point, you have an External S-TAP container that is ready to deploy and each collector that is SSL-enabled has a valid SSL certificate. The next steps are to prepare and run the deployment scripts. You can run the scripts from the External S-TAP host or another machine that has access to the External S-TAP host and is running Linux.

If you plan to use the load balancing script to create a load balancing solution, you need to prepare the load balancer script. The first step that the deployment script takes is to call the load balancing script. For more information about the load balancer script, see Load balancer scripts.
Note: Using the load balancing script is recommended, but not required. If your site chooses not to use the load balancing script, make sure that you have another load balancing strategy in place.
Run the External S-TAP deployment script, container_mgmt.sh, in interactive mode to set the correct options for your site in an iterative fashion.
Note: If you use persistent storage (see --persist), you need to initialize it before running the script. Initializing the persistent storage allows the Docker container to access data. For example,
```
docker run --rm -v my-vol:/persistent busybox /bin/sh -c 'touch /persistent/.initialized && chown -R 1000:1000 /persistent'
```

Note: The deployment and load balancing scripts are available on GitHub at https://github.com/IBM/Guardium_External_S-TAP. Before you run or modify the scripts, be sure to read the CONTRIBUTOR.md and README.md files.

External S-TAP deployment example

The following example walks through the script that creates the External S-TAP containers in interactive mode:

From your Linux® command line, cd to the directory where the container_mgmt.sh and lb_interface_nginx.sh scripts are located.
From the command line, call the container_mgmt.sh script, along with the --state-file and --lb-script parameters, as discussed in Table 1. For example,
```
~> container_mgmt.sh --state-file sample_state --lb-script lb_interface_nginx.sh 
```
Note: The --state-file parameter is always required. The --lb-script parameter is required if you are using the load balancing script (recommended). If you do not include --lb-script, a warning message displays.
At the prompt, specify the action that you want to take, as described in Table 2. Depending on the action you select, the deployment script asks for the information it needs.
For this example, at the would you like to prompt, select C and then press Enter to create External S-TAP containers.
Tip: If you are installing External S-TAP on a cloud host, select P to print the list of environment variables that are required to configure your cloud instance for the External S-TAP container.
At the next prompt, What host do you want to use to host the service containers?, you can either enter one or more host names (comma separated), or press Enter to select the default (localhost).
The script echoes the actual parameter name and argument, as shown:
```
What host do you want to use to host the service containers? [localhost]
Non-interactive parameter: --svc-host localhost
```
Tip: Copy each parameter and argument into Notepad or another editor to build up the command line as you determine the required parameters. You can then copy and paste the completed command line into your Linux shell.
Continue responding to each prompt.
- For parameters where you accept the default, press Enter.
- For parameters for which you want to change the default (or which has no default), enter the new value and then press Enter.
After you successfully run the script, the host computer will ssh to the Guardium host and run commands to set up the External S-TAP containers and the load balancer.

When you run the deployment script in an on-premises environment, it creates a cluster of External S-TAP containers. External S-TAPs monitor all transactions, perform TLS decryption and reencryption (if the database is SSL-enabled), and forwards the traffic to the Guardium system. It also (optionally) configures a load balancer that clients can connect to. The load balancer then forwards these connections to one of the External S-TAP containers.

Use Table 3 to determine which parameters you need. The parameters are shown in the order that they are called when you create a new cluster (that is, when you select the --c option).

Note: You can rename or edit any of the scripts as required for your installation. Make sure that any changes to one script (such as changing the name of the load balancing script) are propagated to any other scripts that call them. Do not change parameter names.

Required command line parameters

The parameters in Table 1 must be available on the command line. If you do not include --lb-script on the command line, you must provide your own load balancing solution. For more information, see Load balancer scripts

Table 1. Required command line parameters
Parameter	Meaning
--state-file `filename`	Required. The name of the file in which the state is recorded. For example: `--state-file /ext_stap_state` Note: You must specify the state file in the command line.
--lb-script `filename`	The name of the load balancer deployment script. If you do not include the name of the load balancer script, you must configure the load balancer separately. For your convenience, two default scripts are available: lb_interface_echo.sh - An example script for a generic load balancer (does not work as is). lb_interface_nginx.sh - An example script to create an NGINX-based load balancer. Note: To use the load balancer script, you must specify the parameter and script name in the command line.

Selecting the action

Use the parameters in Table 2 to specify the action you want to take each time you run the deployment script. In general, you use this script to create (--c) a cluster of External S-TAP containers. However, you can also use the same script to delete clusters, print the Docker container environment variables, and take other actions, as described in Table 2.

Table 2. External S-TAP action parameters
Parameter	Meaning
--ni	Run this script in non-interactive mode. Use interactive mode to set parameters as needed. After the script is set up for your environment, you can run the script in non-interactive mode.
--c	Create a cluster.
--d	Delete an existing cluster.
--e	Enable interception, that is restart intercepting database traffic. Requires the load balancer integration script. This command is generally only used for support and testing purposes.
--p	Do not create a cluster, but print the Docker container environment variables. The output is saved in the state file. For hosting in the cloud, use the --p parameter to print the environment variables you need to configure your cloud instance for the External S-TAP container.
--r	Remove interception, that is, stop intercepting database traffic. Requires the load balancer integration script. This command is generally only used for support and testing purposes.
--u	Upgrade an existing cluster.
--z	Clean up zombie instances, that is, stop and delete old containers that are still running on the host.

Deployment script parameters

The remaining deployment script parameters specify important information for your deployment, such as host names, repository names, and the number of containers to deploy. When you run the script in interactive mode, you are prompted for the value of each parameter. For optional parameters, or to accept default values for required parameters, you can press Enter to continue without entering any information.

Note: The parameters that display depend on the action you select when you call the External S-TAP deployment script.

Table 3. External S-TAP deployment script parameters
Parameter	Script Question/Meaning
--svc-host `host/ip`	`What host do you want to use to host the service containers?` The host name or IP address of the host or hosts on which to create the containers. Separate multiple host names with a comma. The default is `$SVC_HOST`.
--svc-port-range `m-n`	`What is the port range for the exported service port?` The exported port number for the Docker container. You can specify a range of available ports between `m-n` (inclusive). In this case, the host dynamically determines the port number for each Docker container. For example: `--svc-port-range 6100-6500` The default is 0, which uses the values from: `/proc/sys/net/ipv4/ip_local_port_range`
--svc-host-user `username`	`What user will be logging in to the host to start the service containers?` . The user name of the user who creates containers on the Docker host machine. The default is the current user, `$SVC_HOST_USER`
--svc-image `image`	`Enter the hash or tag for the service container image:` The name or hash of the External S-TAP image from Docker. For example: `--svc-image store/ibmcorp/guardium_external_s-tap:v10.6.0`
--repo-user `username`	`What is the username to be used if login is required to pull the service container image?` The user name of the user who logs in to the repository from which the External S-TAP Docker image is pulled.
--repo-pass `password`	`What is the password for user?` The password for the repo-user user name. Tip: Before running the deployment script, log in to Docker (on the Docker host machine) with docker login to save your login information to ~/.docker/config.json. After you are logged in, you do not need to enter the --repo-user and --repo-pass parameters.
--svc-container-num `num`	`How many service containers would you like to create?` The number of External S-TAP Docker containers to create for this database inspection cluster. The default is 1.
--uuid `UUID`	`Please enter a UUID for this group:` The UUID of the External S-TAP cluster. The default is a random UUID generated from `uuidgen`.
--proxy-num-workers `n`	`Enter the number of workers for each service container of Guardium External S-TAP:` The number of worker threads for the External S-TAP to use. You can set the number of worker threads from the Guardium collector Edit External S-TAP group page after the cluster is created. The default is 1.
--db-host `host/ip`	`Enter the hostname or IP to which the DB the Guardium External S-TAP group will be relaying traffic:` The host name or IP address to the computer where the External S-TAP will forward connections.
--db-type `string`	`Enter the type of database for the DB host:` The database type for External S-TAP traffic. You can set the database type from the Guardium collector Edit External S-TAP group page after the cluster is created. Supported databases are listed on the Database tab of the Deploy External S-TAP page.
--db-port `port`	`Enter the port for the DB to which the Guardium External S-TAP group will be relaying traffic:` The port number needed to access this cluster. You can set the port number from the Guardium collector Edit X-TAP group page after the cluster is created.
override_server_ip`IP address`	`Enter an IP to override and force the server IP to be reported as (optional and uncommon, leave blank if not needed)`
--proxy-protocol `n`	`If proxy protocol version 1 is enabled for the DB traffic, enter 1, otherwise enter 0:` Specifies whether the proxy protocol is enabled for the database traffic. For more information, see https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt. 0 - Not enabled (default). 1 - Protocol version 1. If your load balancer supports proxy protocol, the protocol inserts data at the beginning of the connection to share the client's IP address with External S-TAP. With proxy protocol, connections are reported as being from the client to the DB host. You can change this setting from the Guardium collector Edit External S-TAP group page after the cluster is created.
--invalid-cert-disconnect	`Do you wish to disconnect the clients if the DB server certificate cannot be verified? (y/n)` If the database server certificate cannot be verified, terminate the client connection.
--invalid-cert-notify	`Do you wish to log an error message if the DB server certificate cannot be verified? (y/n)` If the database server certificate cannot be verified, continue running and log a warning.
--proxy-secret `string`	Depending on how External S-TAP is configured on your system, you might see one of the following prompts: `If traffic is encrypted and you are generating CSRs on the collector and signing them separately, enter the secret token which will be used to retrieve the key and signed certificate from the Guardium Collector:` . The shared secret string, or token, needed to retrieve keys from the collector for External S-TAP. Run `show certificate External S-TAP` from the CLI on the Guardium collector to view the token you need to enter for proxy-secret. Or: `If traffic is encrypted and you have a signing certificate stored on the collector to automatically sign CSRs generated by External S-TAP, enter the Name field for the CSR's CN:` In this case, use the shared secret string to generate a CSR container that is signed by the collector. In this case, the --proxy-csr-name is required. In either case, --proxy-secret is required if you want to use encrypted External S-TAP traffic.
--proxy-csr-name `string`	`If traffic is encrypted and you have a signing certificate stored on the collector to automatically sign CSRs generated by External S-TAP, enter the Name field for the CSR's CN:` Required if you have a signing certificate stored on the collector. Enter a name for the CSR's common name, or CN.
--proxy-csr-country `string`	`Enter the Country field for the CSR's CN:`
--proxy-csr-province `string`	`Enter the Province field for the CSR's CN:` Enter the state or province for the CSR's CN.
--proxy-csr-city `string`	`Enter the City field for the CSR's CN:`
--proxy-csr-organization `string`	`Enter the Organization field for the CSR's CN:`
--proxy-csr-keylength `integer`	`Enter the length for the CSRs private key:` The length of the CSR private key must be between 2048 and 8192.
--sqlguard-ip `host/IP address`	`Enter the hostname or IP of the Guardium Collector:` Required. The collector host name or IP address for External S-TAP to relay decrypted traffic.
--sqlguard-cert-cn `cn`	`CN to match when verifying collector certificates. Requires a derived container image with a CA populated at ${GUARDIUM_CA_PATH}` If your site chooses to verify collector certificates, enter the CN (common name) of the collector's certificate. Leave this entry blank to disable verification. For more information, see Verify collector certificates (optional).
--participate-in-load-balancing `char`	`Participate in load balancing or failover? 0: failover/no lb, 1) split, 2) redundancy, 3) not allowed, 4) threaded:` . Specify the type of load balancing solution to use. You can change this setting from the Guardium collector Edit External S-TAP group page later.
--kill-after `n`	`Enter the number of seconds to wait before forcefully stopping the old containers (0 is wait 30s, but don't forcefully stop):` When stopping a container, if the container does not shut down within `n` seconds, forcefully remove it. The default is to wait 30 seconds but don't force removal. Note: This parameter does not display when creating containers.
--state-file `filename`	`Name of the file in which the state is recorded.` Required. The name of the state file, for example `\"./cluster_state\"`.
--envvar `environment setting`	For support purposes only.
--persistent `Docker volume`	`Persistent storage source` The name of a Docker persistent volume. The volume must be accessible and shared between all of the nodes at the same path. If needed, change the owner on the host machine directory to the same UID as the UID of the External S-TAP. For example, `chown -R 1000:1000 <path_to_External_S-TAP volume>` Note: Be sure to initialize the persistent storage before you run the script.