Product Documentation

Appearance

All platforms

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. If a browser is not available (ie. restricted console, ssh), fallback to device login if the authorization endpoint supports it.

--auth-device

Authenticate the connection by device login flow, utilizing a browser URL. You may use this option on a restricted console, copy the URL given and code, and proceed to authenticate with a separate browser or device that has a browser.

--auth-direct

Authenticate the connection directly from the ybtools command (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-scopes

Supply override for scopes requested when authenticating. Some IDPs such as Azure AD require this to be specified as <client_id>/.default, which returns an access token that can be validated by an external resource owner, such as Yellowbrick Database. Alternatively, you can set the YBAUTHSCOPES environment variable.

--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.

If this option is not specified, the default user is the current OS user on the client system. Users who connect to tools such as ybload via Kerberos SSO, for example, can do so directly without specifying a username or a password.

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.