Transfer files to a Linux instance with scp, sftp, or rsync

Before you begin

Complete these checks before transferring files.

1. Retrieve the instance public IP address

   The instance must have public bandwidth enabled. Record the public IP address from the Instance list page in the ECS console.

2. Configure security group rules

   These tools use SSH (port 22 by default). Ensure the security group allows inbound TCP traffic on this port from your local IP address.

   • Action: Allow

   • Protocol Type: Custom TCP

   • Port Range: 22/22 (or your custom SSH port)

   • Source: Set to your local public IP address for security.

     Get your IP by running curl ifconfig.me or curl ip.sb in your local terminal.

3. Check the internal firewall

   The OS firewall (such as firewalld or ufw) may also block the connection.

   1. Log on to the instance and check the firewall status.

   2. If the firewall is active, ensure it allows SSH or port 22. To open a port or service, see the documentation for your OS.

Upload files or directories to an instance

Upload a file or folder to your instance. You will be prompted for a password.

# Upload a single file to the instance
sudo scp <local_file_path> <instance_username>@<public_ip_address>:<remote_directory_path>

# Upload a local directory to the instance
sudo scp -r <local_directory_path> <instance_username>@<public_ip_address>:<remote_directory_path>

Example:

Upload /opt/test.txt to /home/ecs-user/ on an instance with public IP 1xx.xxx.xxx.121:

sudo scp /opt/test.txt ecs-user@1xx.xxx.xxx.121:/home/ecs-user/

Download files or directories from an instance

Download a file from your instance. You will be prompted for a password.

Note:scp is inefficient for many small files. Archive them into a .tar.gz file before transferring, or use rsync.

# Download a single file to your local machine
sudo scp <instance_username>@<public_ip_address>:<remote_file_path> <local_directory_path>

# Download a directory from the instance to your local machine
sudo scp -r <instance_username>@<public_ip_address>:<remote_directory_path> <local_directory_path>

Example:

Download /home/ecs-user/test.txt from an instance with public IP 1xx.xxx.xxx.121 to the local /opt/ directory:

sudo scp ecs-user@1xx.xxx.xxx.121:/home/ecs-user/test.txt /opt/

Connect to the instance

Establish an sftp connection. Once connected, the prompt changes to sftp>.

sudo sftp <instance_username>@<public_ip_address>

Upload files or directories to an instance

# Upload a single file
sftp> put <local_file_path> <remote_directory_path>

# Upload an entire directory
sftp> put -r <local_directory_path> <remote_directory_path>

Examples:

• Upload /opt/test.txt to /home/ecs-user/ on the instance:

  sftp> put /opt/test.txt /home/ecs-user

• To upload the local directory /opt/test/ to the /home/ecs-user/ directory on the instance:

  sftp> put -r /opt/test/ /home/ecs-user/

Download files or entire directories from an instance

# Download a single file
sftp> get <remote_file_path> <local_directory_path>

# Download an entire directory
sftp> get -r <remote_directory_path> <local_directory_path>

Examples:

• To download the file /home/ecs-user/test.txt from the instance to your local /opt directory:

  sftp> get /home/ecs-user/test.txt /opt

• To download the directory /home/ecs-user/test/ from the instance to your local /opt directory:

  sftp> get -r /home/ecs-user/test/ /opt

Resume a transfer

If a large file transfer is interrupted, you can use the reput (upload) and reget (download) commands to resume the transfer from where it left off.

# Resume an upload
sftp> reput <local_file_path> <remote_file_path>

# Resume a download
sftp> reget <remote_file_path> <local_file_path>

Note: SFTP resumable transfer is effective only for single files. If a directory transfer is interrupted, we recommend exiting SFTP and using rsync for efficient synchronization.

Disconnect the session

When you have finished your tasks, use the quit or bye command to exit the sftp session.

Install the tool

Ensure rsync is installed on both your local machine and the instance.

# On CentOS / Alibaba Cloud Linux
sudo yum install -y rsync

# On Debian / Ubuntu
sudo apt-get update && sudo apt-get install -y rsync

Common options

The standard usage of rsync often includes the -avz options:

• -a (archive): Archive mode, equivalent to -rlptgoD. It synchronizes recursively and preserves all file attributes, such as permissions and timestamps.

• -v (verbose): Displays detailed information about the transfer process.

• -z (compress): To save bandwidth, it compresses data during transfer. However, on high-bandwidth links, CPU compression can become a bottleneck, and omitting -z might be faster.

Upload or synchronize files and directories to an ECS instance

To upload files to an instance, run the following command from your local machine. You will be prompted to enter your password.

sudo rsync -avz -e ssh <local_path> <logon_username>@<public_ip_address>:<remote_path>

Examples:

• To upload the file /opt/test.txt to the /home/ecs-user directory of an instance with the public IP address 1xx.xxx.xxx.121:

  sudo rsync -avz -e ssh /opt/test.txt ecs-user@1xx.xxx.xxx.121:/home/ecs-user

• To synchronize the local directory /opt/test/ with the /home/ecs-user/test directory on the instance with public IP address 1xx.xxx.xxx.121:

  sudo rsync -avz -e ssh /opt/test/ ecs-user@1xx.xxx.xxx.121:/home/ecs-user/test

Download or synchronize files and directories from an instance

To download files from an instance to your local machine, run the following command locally. You will be prompted to enter your password.

sudo rsync -avz -e ssh <instance_username>@<public_ip_address>:<remote_path> <local_path>

• Handle a large number of small files: archive first, then transfer

  Transferring a directory with thousands of small files is inefficient with any of these tools because of the connection and metadata overhead for each file. The best practice is to archive and compress the directory into a single file (for example, .tar.gz) on the source machine, transfer the archive, and then extract it on the destination machine.

• Simplify commands with an SSH configuration file

  You can simplify connection and transfer commands by creating an alias for your ECS instance (for example, my-prod-server) in your local ~/.ssh/config file.

  # Add the following to ~/.ssh/config
  Host my-prod-server
      HostName 118.178.x.x
      User ecs-user
      Port 22
      IdentityFile ~/.ssh/id_rsa_aliyun
      ServerAliveInterval 60

  This simplifies your scp and rsync commands:

  # Original command:
  sudo scp -i ~/.ssh/id_rsa_aliyun local.txt ecs-user@118.178.x.x:/remote/
  # New command:
  sudo scp local.txt my-prod-server:/remote/
  
  # Original command:
  sudo rsync -avz -e "ssh -i ~/.ssh/id_rsa_aliyun" local_dir/ ecs-user@118.178.x.x:/remote_dir/
  # New command:
  sudo rsync -avz local_dir/ my-prod-server:/remote_dir/