.TH "GCLOUD_TRANSFER_AGENTS_INSTALL" 1



.SH "NAME"
.HP
gcloud transfer agents install \- install Transfer Service agents



.SH "SYNOPSIS"
.HP
\f5gcloud transfer agents install\fR \fB\-\-pool\fR=\fIPOOL\fR [\fB\-\-count\fR=\fICOUNT\fR] [\fB\-\-creds\-file\fR=\fICREDS_FILE\fR] [\fB\-\-docker\-network\fR=\fINETWORK\fR] [\fB\-\-[no\-]enable\-multipart\fR] [\fB\-\-id\-prefix\fR=\fIID_PREFIX\fR] [\fB\-\-logs\-directory\fR=\fILOGS_DIRECTORY\fR;\ default="/tmp"] [\fB\-\-memlock\-limit\fR=\fIMEMLOCK_LIMIT\fR;\ default=64000000] [\fB\-\-mount\-directories\fR=[\fIMOUNT\-DIRECTORIES\fR,...]] [\fB\-\-proxy\fR=\fIPROXY\fR] [\fB\-\-s3\-compatible\-mode\fR] [\fB\-\-hdfs\-namenode\-uri\fR=\fIHDFS_NAMENODE_URI\fR\ \fB\-\-hdfs\-username\fR=\fIHDFS_USERNAME\fR\ \fB\-\-hdfs\-data\-transfer\-protection\fR=\fIHDFS_DATA_TRANSFER_PROTECTION\fR] [\fB\-\-kerberos\-config\-file\fR=\fIKERBEROS_CONFIG_FILE\fR\ \fB\-\-kerberos\-keytab\-file\fR=\fIKERBEROS_KEYTAB_FILE\fR\ \fB\-\-kerberos\-user\-principal\fR=\fIKERBEROS_USER_PRINCIPAL\fR\ \fB\-\-kerberos\-service\-principal\fR=\fIKERBEROS_SERVICE_PRINCIPAL\fR] [\fIGCLOUD_WIDE_FLAG\ ...\fR]



.SH "DESCRIPTION"

Install Transfer Service agents to enable you to transfer data to or from POSIX
filesystems, such as on\-premises filesystems. Agents are installed locally on
your machine and run inside Docker containers.



.SH "EXAMPLES"

To create an agent pool for your agent, see the \f5gcloud transfer agent\-pools
create\fR command.

To install an agent that authenticates with your user account credentials and
has default agent parameters, run:

.RS 2m
$ gcloud transfer agents install \-\-pool=AGENT_POOL
.RE

You will be prompted to run a command to generate a credentials file if one does
not already exist.

To install an agent that authenticates with a service account with credentials
stored at '/example/path.json', run:

.RS 2m
$ gcloud transfer agents install \-\-creds\-file=/example/path.json \e
    \-\-pool=AGENT_POOL
.RE

To install an agent using service account impersonation, run:

.RS 2m
$ gcloud transfer agents install \-\-creds\-file=/example/path.json \e
    \-\-pool=CUSTOM_AGENT_POOL \e
    \-\-impersonate\-service\-account=impersonated\-account@project\-id.ia\e
m.gserviceaccount.com
.RE

Note : The \f5\-\-impersonate\-service\-account\fR flag only applies to the API
calls made by gcloud during the agent installation and authorization process.
The impersonated credentials are not passed to the transfer agent's runtime
environment. The agent itself does not support impersonation and will use the
credentials provided via the \f5\-\-creds\-file\fR flag or the default gcloud
authenticated account for all of its operations. To grant the agent permissions,
you must provide a service account key with the required direct roles (e.g.,
Storage Transfer Agent, Storage Object User)



.SH "REQUIRED FLAGS"

.RS 2m
.TP 2m
\fB\-\-pool\fR=\fIPOOL\fR

The agent pool to associate with the newly installed agent. When creating
transfer jobs, the agent pool parameter will determine which agents are
activated.


.RE
.sp

.SH "FLAGS"

.RS 2m
.TP 2m
\fB\-\-count\fR=\fICOUNT\fR

Specify the number of agents to install on your current machine. System
requirements: 8 GB of memory and 4 CPUs per agent.

Note: If the 'id\-prefix' flag is specified, Transfer Service increments a
number value after each prefix. Example: prefix1, prefix2, etc.

.TP 2m
\fB\-\-creds\-file\fR=\fICREDS_FILE\fR

Specify the path to the service account's credentials file.

No input required if authenticating with your user account credentials, which
Transfer Service will look for in your system.

Note that the credentials location will be mounted to the agent container.

.TP 2m
\fB\-\-docker\-network\fR=\fINETWORK\fR

Specify the network to connect the container to. This flag maps directly to the
\f5\-\-network\fR flag in the underlying 'docker run' command.

If binding directly to the host's network is an option, then setting this value
to 'host' can dramatically improve transfer performance.

.TP 2m
\fB\-\-[no\-]enable\-multipart\fR

Split up files and transfer the resulting chunks in parallel before merging them
at the destination. Can be used make transfers of large files faster as long as
the network and disk speed are not limiting factors. If unset, agent decides
when to use the feature. Use \fB\-\-enable\-multipart\fR to enable and
\fB\-\-no\-enable\-multipart\fR to disable.

.TP 2m
\fB\-\-id\-prefix\fR=\fIID_PREFIX\fR

An optional prefix to add to the agent ID to help identify the agent.

.TP 2m
\fB\-\-logs\-directory\fR=\fILOGS_DIRECTORY\fR; default="/tmp"

Specify the absolute path to the directory you want to store transfer logs in.
If not specified, gcloud transfer will mount your /tmp directory for logs.

.TP 2m
\fB\-\-memlock\-limit\fR=\fIMEMLOCK_LIMIT\fR; default=64000000

Set the agent container's memlock limit. A value of 64000000 (default) or higher
is required to ensure that agent versions 1.14 or later have enough locked
memory to be able to start.

.TP 2m
\fB\-\-mount\-directories\fR=[\fIMOUNT\-DIRECTORIES\fR,...]

If you want to grant agents access to specific parts of your filesystem instead
of the entire filesystem, specify which directory paths to mount to the agent
container. Multiple paths must be separated by commas with no spaces (e.g.,
\-\-mount\-directories=/system/path/to/dir1,/path/to/dir2). When mounting
specific directories, gcloud transfer will also mount a directory for logs
(either /tmp or what you've specified for \-\-logs\-directory) and your Google
credentials file for agent authentication.

It is strongly recommended that you use this flag. If this flag isn't specified,
gcloud transfer will mount your entire filesystem to the agent container and
give the agent root access.

.TP 2m
\fB\-\-proxy\fR=\fIPROXY\fR

Specify the HTTP URL and port of a proxy server if you want to use a forward
proxy. For example, to use the URL 'example.com' and port '8080' specify
\'http://www.example.com:8080/'

Ensure that you specify the HTTP URL and not an HTTPS URL to avoid
double\-wrapping requests in TLS encryption. Double\-wrapped requests prevent
the proxy server from sending valid outbound requests.

.TP 2m
\fB\-\-s3\-compatible\-mode\fR

Allow the agent to work with S3\-compatible sources. This flag blocks the
agent's ability to work with other source types (e.g., file systems).

When using this flag, you must provide source credentials either as environment
variables \f5AWS_ACCESS_KEY_ID\fR and \f5AWS_SECRET_ACCESS_KEY\fR or as default
credentials in your system's configuration files.

To provide credentials as environment variables, run:

.RS 2m
AWS_ACCESS_KEY_ID="id" AWS_SECRET_ACCESS_KEY="secret" gcloud transfer agents install \-\-s3\-compatible\-mode
.RE


.RE
.sp

.SH "HDFS FLAGS"

.RS 2m
.TP 2m
\fB\-\-hdfs\-namenode\-uri\fR=\fIHDFS_NAMENODE_URI\fR

A URI representing an HDFS cluster including a schema, namenode, and port.
Examples: "rpc://my\-namenode:8020", "http://my\-namenode:9870".

Use "http" or "https" for WebHDFS. If no schema is provided, the CLI assumes
native "rpc". If no port is provided, the default is 8020 for RPC, 9870 for
HTTP, and 9871 for HTTPS. For example, the input "my\-namenode" becomes
"rpc://my\-namenode:8020".

.TP 2m
\fB\-\-hdfs\-username\fR=\fIHDFS_USERNAME\fR

Username for connecting to an HDFS cluster with simple auth.

.TP 2m
\fB\-\-hdfs\-data\-transfer\-protection\fR=\fIHDFS_DATA_TRANSFER_PROTECTION\fR

Client\-side quality of protection setting for Kerberized clusters. Client\-side
QOP value cannot be more restrictive than the server\-side QOP value.
\fIHDFS_DATA_TRANSFER_PROTECTION\fR must be one of: \fBauthentication\fR,
\fBintegrity\fR, \fBprivacy\fR.


.RE
.sp

.SH "Kerberos FLAGS"

.RS 2m
.TP 2m
\fB\-\-kerberos\-config\-file\fR=\fIKERBEROS_CONFIG_FILE\fR

Path to Kerberos config file.

.TP 2m
\fB\-\-kerberos\-keytab\-file\fR=\fIKERBEROS_KEYTAB_FILE\fR

Path to a Keytab file containing the user principal specified with the
\-\-kerberos\-user\-principal flag.

.TP 2m
\fB\-\-kerberos\-user\-principal\fR=\fIKERBEROS_USER_PRINCIPAL\fR

Kerberos user principal to use when connecting to an HDFS cluster via Kerberos
auth.

.TP 2m
\fB\-\-kerberos\-service\-principal\fR=\fIKERBEROS_SERVICE_PRINCIPAL\fR

Kerberos service principal to use, of the form "<primary>/<instance>". Realm is
mapped from your Kerberos config. Any supplied realm is ignored. If not passed
in, it will default to "hdfs/<namenode_fqdn>" (fqdn = fully qualified domain
name).


.RE
.sp

.SH "GCLOUD WIDE FLAGS"

These flags are available to all commands: \-\-access\-token\-file, \-\-account,
\-\-billing\-project, \-\-configuration, \-\-flags\-file, \-\-flatten,
\-\-format, \-\-help, \-\-impersonate\-service\-account, \-\-log\-http,
\-\-project, \-\-quiet, \-\-trace\-token, \-\-user\-output\-enabled,
\-\-verbosity.

Run \fB$ gcloud help\fR for details.



.SH "NOTES"

This variant is also available:

.RS 2m
$ gcloud alpha transfer agents install
.RE