Common Options in ybtools

The Java-based client tools, and to a certain extent, ybsql, share some common options and equivalent environment variables. These options define connectivity settings, logging behavior, and security credentials. For information about options that are specific to one client tool, see:

See also Object Storage Options.

General Options

-?, --help
Return basic usage information and command options.
--help-advanced
Return usage information for more advanced command options.
--java-version
Return the Java version that is running on the client system. The client tools require the 64-bit version of Java 8 (also known as Java 1.8). Java 9 and 10 are not supported.
--version
Display the version of each tool you are running (as part of ybtools). This option is not intended to be combined with other options. For example: 
$ ./ybunload --version
ybunload version 6.1.12-7a4d6a43.3360
...
$ ./ybload --version
ybload version 6.1.12-7a4d6a43.3360

Connection and Authentication Options

Yellowbrick client tools support the Open Authorization (OAuth 2.0) and OpenID Connect (OIDC) standard for database connections.
--auth-browser
Authenticate the connection by opening a browser window on the client machine and entering a password. -U username is required when you use this option. You may need to make sure that your client system is configured to open a default browser.
--auth-direct
Authenticate the connection directly with a username and password (as opposed to opening a browser). The -U username option and YBPASSWORD, --password, or -W are required when you use direct authentication.
--auth-issuer
Specify the URL of the OAuth/OIDC issuer. This URL belongs to the identity provider (IDP) that issues JWT tokens for user connections. The IDP checks that the user exists in the specified realm, then returns a JWT token, which is a short-lived password for authentication for that user. Alternatively, you can set the YBAUTHISSUER environment variable.
This option must be specified for any kind of OAuth/OIDC connection.
For example: 
--auth-issuer https://cn.beta.yellowbrickcloud.com/auth/realms/mycompany.com

where cn.beta.yellowbrickcloud.com/auth is the Yellowbrick IDP, which has some number of realms, such as mycompany.com.

--auth-token AUTH_TOKEN
Supply a JWT string in the command line explicitly. Alternatively, you can set the YBAUTHTOKEN environment variable.
--client-id
Specify the Yellowbrick Data Warehouse client ID, which is ybauth. Alternatively, you can set the YBCLIENTID environment variable.

This option is required for OAuth/OIDC authentication.

--cluster
Name of the virtual compute cluster to use.
--dbname, -d
Name of the database used for the connection. The default is yellowbrick.
--host
Host name.
--initial-connection-timeout NUMBER
Number of seconds to wait for initial connections to the database. The default is 120. This timeout option ensures that an operation does not wait too long when there is a basic problem with incorrect connection parameters, or a firewall is preventing connection errors from reaching the client. To allow an unlimited wait time, set this option to 0.
-p, --port
Specify the database server port. Alternatively, set this value with the YBPORT environment variable. Default: 5432
-U, --username
Specify the database user who is running the command. Alternatively, set this value with the YBUSER environment variable.
Note: The ybload user must have INSERT privileges on the target table but does not have to own the table.
-W, --password
Interactively prompt for the database user's password. Do not enter a password on the command line if you use this option. For non-interactive password entry, set the YBPASSWORD environment variable.

Logging Options

--log-level OFF | ERROR | WARN | INFO | DEBUG | TRACE
Specify the logging level for the default console output. The default level is INFO. (Use the --logfile-log-level option to specify the logging level for a named log file.)
--logfile STRING
Specify the name and location of a log file. If the specified file already exists, it will be truncated. If this option is not specified, no log file is written. When you specify this --logfile option, also specify a --logfile-log-level value other than OFF.
Note: When object storage is used for loading or unloading data, logs must be written to the local file system. Specifying a log file in an object storage location, such as an S3 bucket, is not supported.
--logfile-log-level OFF | ERROR | WARN | INFO | DEBUG | TRACE
Specify the logging level for a given log file (as defined with the --logfile option). If the level is not specified, it defaults to the --log-level value. You must specify a --logfile-log-level value other than OFF when you specify the --logfile option.
-q, --quiet
Do not write any output to the screen. This option is suitable for cron invocations. If this option is specified, you must also specify --logfile and --logfile-log-level.

Security Options

--cacert STRING
Customize trust with secured communication; use this option in combination with the --secured option. Enter the file name of a custom PEM-encoded certificate or the file name and password for a Java KeyStore (JKS).
For PEM format, the file must be named with a .pem, .cert, .cer, .crt, or .key extension. For example: 
--cacert cacert.pem
For JKS format, files are always password-protected. Use the following format:
--cacert yellowbrick.jks:changeit

where the : character separates the file name from the password of the keystore.

See also Verifying SSL/TLS Encryption and

Secure Connections for Java-based ybtools.
--disable-trust, -k
Disable SSL/TLS trust when using secured communications. Trust is enabled by default. See also Verifying SSL/TLS Encryption.
Important: This option is not supported for use on production systems and is only recommended for testing purposes. It may be useful to disable trust during testing, then enable it when a formal signed certificate is installed on the cluster.
--secured
Use SSL/TLS to secure all communications. By default, loads are "promoted" to secure SSL connections even if --secured is not specified, and an SSL connection is always attempted.