Configure access to a source: file system

To transfer data from an on-premises or private cloud file system (such as POSIX-compliant file systems, NFS, or SMB), you must install and configure Storage Transfer Service agents on machines with network access to the source files.

Prerequisites

Before configuring your transfer, ensure you have set up the following:

• User permissions: Ensure your user account or user-managed service account has permission to configure transfer jobs and agent pools. See Required user permissions.
• Agent-based project-level permissions: Ensure you have configured the required project-level roles for your service agent and transfer agent account. See Agent-based project-level permissions.
• Destination permissions: Depending on your transfer destination, configure the required sink permissions:
  • For transfers to Cloud Storage, see Configure access to a sink: Cloud Storage.
  • For transfers to another file system, see Configure access to a sink: file system.

Local file system permissions

Transfer agents run inside Docker or Podman containers on your host machines. To enable agents to read your files:

1. OS user permissions: Ensure the operating system user running the container has read (and execute on directories) permissions for all files and directories you plan to transfer.

2. Mount directories: When installing your agents, mount the directories you want to copy into the container using the --mount-directories flag (or -v flags in Docker):

   gcloud transfer agents install --pool=AGENT_POOL_NAME \
     --mount-directories=/path/to/source/dir
   

   Caution: If multiple agents in the same agent pool run on different physical machines, they must all have uniform network access (such as a shared NFS mount) to the exact same paths. If one agent cannot access a path assigned to it, the transfer job fails.

To restrict which host directories agents can view, see Restricting agent directory access.

Performance and optimization

• To maximize throughput when transferring from large file systems, install multiple agents in your source agent pool (recommended minimum of 3). See Best practices for transfer agents.
• For files larger than 1 GB, consider enabling multipart uploads.

What's next

• Learn how to Install transfer agents.
• Learn how to Create an agent pool.
• Learn how to Configure access to a sink: Cloud Storage.
• Learn how to Configure access to a sink: file system.