The secure copy program, scp, obeys keywords in your client configuration file just as ssh does. In addition, scp provides other features and options that we'll cover in this section. Remember that scp supports several options for logging and debugging, so you can watch what's going on when it runs. [7.3]
So far, we've described the syntax of scp only in general: [2.2.1]
scpname-of-sourcename-of-destination
Each of the two names, or path specifications, on the command line represents files or directories in the following manner (it is fairly consistent with the behavior of Unix cp or rcp):
If name-of-source is a file, name-of-destination may be a file (existing or not) or a directory (which must exist). In other words, a single file may be copied to another file or into a directory.
If name-of-source is two or more files, one or more directories, or a combination, name-of-destination must be an existing directory into which the copy takes place.[115] In other words, multiple files and directories may be copied only into a directory.
Both name-of-source and name-of-destination may have the following form from left to right:
The username of the account containing the file or directory, followed by @. This part is optional, and if omitted, the value is the username of the user invoking scp.
The hostname of the host containing the file or directory, followed by a colon. This part is optional, if the path is present, and the username isn't; if omitted, the value is localhost. Tectia permits an optional TCP port number for the SSH connection to be inserted between the hostname and the colon, preceded by a hash sign.
The directory path to the file or directory. (Optional if the hostname is present.) Relative pathnames are assumed relative to the default directory, which is the current directory (for local paths) or the user's home directory (for remote paths). If omitted entirely, the path is assumed to be the default directory.
Although each field is optional, you can't omit them all at the same time, yielding the empty string. Either the hostname (•) or the directory path (•) must be present. Some examples:
The file . /MyFile on localhost
The directory ./MyDirectory on localhost
. (period)The current directory on localhost
The directory ~username on server.example.com
A local file named "server.example.com" (Oops: did you forget the trailing colon? This is a common mistake.)
The file MyFile in the remote user's home directory on server.example.com
The directory ~bob on server.example.com
A local file named "bob@server.example.com" (oops; forgot the trailing colon again)
The file ~bob/MyFile on server.example.com
The file dir/MyFile in the remote user's home directory on server.example.com
The file /dir/MyFile on server.example.com (note the absolute path)
The file ~bob/dir/MyFile on server.example.com
The file /dir/MyFile on server.example.com (although you authenticate as bob, the path is absolute)
The remote user's home directory on server.example.com, via TCP port 2000 (Tectia only)
Here are a few complete examples:
$ scp myfile myfile2 A local copy just like cp $ scp myfile bob@host1: Copy . /myfile to ~bob on host1 $ scp bob@host1:myfile . Copy ~bob/myfile on host1 to . /myfile $ scp host1:file1 host2:file2 Copy file1 from host1 to file2 on host2 $ scp bob@host1:file1 jen@host2:file2 Same as above, but copying from bob's to jen's account
Table 7-3 summarizes the syntax of an scp path.
Table 7-3. scp path specifications
Field | Other syntax | Optional? | Default for local host | Default for remote host |
|---|---|---|---|---|
a Tectia only. | ||||
Username | Followed by @ | Yes | Invoking user's username | Invoking user's username |
Hostname | Followed by : | Only if username is omitted and path is present | None, file is accessed locally | N/A |
Port number a | Preceded by # | Yes | 22 | 22 |
Directory path | N/A | Only if hostname is present | Current (invoking) directory | Username's remote home directory |
scp for OpenSSH has no special support for wildcards in filenames. It simply lets the shell expand them:
$ scp *.txt server.example.com:
Watch out for wildcards in remote file specifications, as they are evaluated on the local machine, not the remote. For example, this attempt is likely to fail:
$ scp server.example.com:*.txt . Bad idea!The Unix shell attempts to expand the wildcard before scp is invoked, but the current directory contains no filename matching "server.example.com:*.txt". The C shell and its derivatives will report "no match" and will not execute scp. Bourne-style shells, noticing no match in the current directory, will pass the unexpanded wildcard to scp, and the copy may succeed as planned, but this coincidental behavior shouldn't be relied on. Always escape your wildcards so that they are explicitly ignored by the shell and are passed to scp:
$ scp server.example.com:\*.txt .
Tectia's scp does its own regular expression matching after shell-wildcard expansion is complete. The sshregex manpage for Tectia (see Appendix B) describes the supported operators. Even so, escape your wildcard characters if you want your local shell to leave them alone.
Sometimes you want to copy not just a single file, but a directory hierarchy. In this case, use the -r option, which stands for recursive. For example, to securely copy the directory /usr/local/bin and all its files and subdirectories to another machine:
$ scp -r /usr/local/bin server.example.com:
If you forget the -r option when copying
directories, scp complains:
$ scp /usr/local/bin server.example.com:
/usr/local/bin: not a regular fileAlthough scp can copy directories, it isn't necessarily the best method. If your directory contains hard links or soft links, they won't be duplicated. Links are copied as plain files (the link targets). Other types of special files, such as named pipes, also aren't copied correctly.[116] A better solution is to use tar, which handles special files correctly, and send it to the remote machine to be untarred, via SSH:
$ tar cf - /usr/local/bin | ssh server.example.com tar xf -
or rsync, tunneled through SSH:
$ rsync -e ssh /usr/local/bin server.example.com:
When scp copies files, the destination files are created with certain file attributes. By default, the file permissions adhere to a umask on the destination host, and the modification and last access times will be the time of the copy. Alternatively, you can tell scp to duplicate the permissions and timestamps of the original files. The -p option accomplishes this:
$ scp -p myfile server.example.com:
For example, if you transfer your entire home directory to a remote machine, you probably want to keep the file attributes the same as the original:
$ scp -rp $HOME server.example.com:myhome/
Again, scp does not duplicate special files and links, so consider tar or rsync -a instead:
$ rsync -a -e ssh /usr/local/bin server.example.com:
After copying a file, Tectia's scp can optionally remove the original if desired. The -u command-line option specifies this:
# Tectia
$ scp myfile server.example.com:
$ ls myfile
myfile
$ scp -u myfile server.example.com:
$ ls myfile
myfile: No such file or directoryIf you've ever wanted a "secure move" command in addition to secure copy, you can define one in terms of scp -u:
# Tectia
$ alias smv='scp -u'Tectia's scp has several features to protect you from running dangerous commands.
Suppose you want to copy a local file, myfile, to a remote directory. You type:
$ scp myfile server.example.com:mydir
$ rm myfileThen you connect to server.example.com and find, to your horror, that mydir was a file, not a directory, and you just overwrote it! Tectia's -d option prevents this tragedy. If the destination isn't a directory, scp complains and exits without copying the file:
# Tectia
$ scp -d myfile server.example.com:mydir
scp: warning: Destination (example.com:mydir) is not a directory.This option is necessary only if you are copying a single file. If you are copying multiple files or a directory, all the scp implementations check by default that the remote destination is a directory.[117]
Another safety feature of Tectia's scp is the -n option, which instructs the program to describe its actions but not perform any copying. This is useful for verifying the behavior of scp before executing a potentially risky command.
# Tectia
$ scp -n myfile server.example.com:
Not transferring myfile -> server.example.com:./myfile (1k)Tectia's scp will refuse to overwrite existing files if you desire. The -I or --interactive option will prompt you before overwriting a destination file:
# Tectia
$ scp -I myfile server.example.com:
Overwrite destination file './myfile' with '/home/smith/myfile' (yes/yes to all/no/no
to all/abort) [y/Y/n/N/a]:nAs an alternative, if you know in advance whether you'll want
to overwrite existing files, use the
--overwrite option (the default is no):
# Tectia
$ scp --overwrite yes myfile server.example.com: Always overwriteIf you're using scp in scripts with passwordless authentication [11.1], you might want to suppress all prompting of the user. That's what the -B option is for, which enables batch mode. When present, this option suppresses all interaction with the user. [7.4.6.4]
$ scp -B myfile server.example.com:
OpenSSH provides the -i option for scp, as it does for ssh, to specify a particular identity file for authentication. [7.4.2]
# OpenSSH
$ scp -i my_favorite_key myfile server.example.com:Tectia has no option like this, but you can get around this
limitation with - o: [7.1.2.1]
# Tectia
$ scp -o "IdentityFile my_identity_file" myfile server.example.com:You can downgrade scp to use the SSH-1 protocol with the -1 option, if you are feeling insecure:
$ scp -1 myfile server.example.com:
or redundantly specify the SSH-2 protocol, which is the default anyway:
# OpenSSH
$ scp -2 myfile server.example.com:You can specify the remote TCP port contacted by scp with the -P option (OpenSSH):
# OpenSSH
$ scp -P 23456 myfile server.example.com:or by appending a hash mark and port number to the file specification (Tectia):
# Tectia
$ scp myfile server.example.com#23456:Both OpenSSH and Tectia can require the use of IP Version 4 or 6, as ssh does, with the -4 and -6 options. [7.4.5.6]
You can set the encryption cipher for scp with the -c option, exactly as for ssh. [7.4.9]
The -l (lowercase L) option of OpenSSH's scp command will limit the bandwidth of the connection, in case you want to avoid saturating a slower network.
# OpenSSH
$ scp -l 1000 myfile server.example.com: Limit bandwidth to 1000 kilobits per secondTectia's scp command can limit the maximum number of concurrent requests it will issue, with the -N option:
# Tectia
$ scp -r -N 5 mydirectory server.example.com: Limit to five concurrent requests in this recursive directory transferFinally, Tectia's -b option controls the buffer size for the file transfer; the default is 32K:
# Tectia
$ scp -b 65536 myfile server.example.com: Set buffer size to 64KOpenSSH's scp command can compress the data before sending it, with the -C option, to speed up transfers: [7.4.14]
# OpenSSH
$ scp -C myfile server.example.com:Tectia does not provide a similar option, but you can get around this and enable compression with -o: [7.1.2.1]
$ scp -o "Compression yes" myfile server.example.com:
Tectia's scp has several options for changing the files in transit. It can change the destination filenames to all lowercase, with the --force-lower-case option:
# Tectia
$ scp --force-lower-case MyFile server.example.com:The destination file on server.example.com will be named myfile rather than MyFile.
Another Tectia transformation involves the treatment of lines in a text file. scp normally transfers files literally, as binary data. You can choose to treat the files specially as text files—that is, lines of ASCII characters terminated by carriage returns and/or linefeeds—with the -a option. Unix, DOS, and Macintosh operating systems use different standards for terminating lines of text, and scp can convert between these standards.
# Tectia
$ scp -a my_text_file server.example.com:The above command assumes that the SSH client and server can
accurately communicate and agree upon the text file standards. If not,
you can use a more advanced syntax for -a that
specifies the line terminators as unix, dos, or mac. This is done by placing src: (for the source machine) and dst: (for the destination machine) after the
-a option. Some examples:
# Tectia
$ scp -asrc:unix -adst:dos myfile server.example.com: Convert from Unix to DOS/Windows format
$ scp -asrc:dos -adst:mac myfile server.example.com: Convert from DOS/Windows to Macintosh format
$ scp -asrc:mac -adst:unix myfile server.example.com: Convert from Macintosh to Unix formatTectia's scp does a few optimizations to avoid transferring unnecessary files and data. Before coping a file, scp compares the file sizes. If they are different, the copy commences, but if they are the same, scp computes an MD5 checksum of the source and destination file. If the checksums are equal, the files are assumed to be identical and no copy takes place, and you'll see a message like this:
myfile: complete md5 match -> transfer skipped
If you always want your files copied, even if they are identical
(i.e., have equal checksums), you can disable the MD5 test with the
--checksum option, providing the value no:
# Tectia
$ scp --checksum no myfile server.example.com: Don't compute checksums for filesTectia's scp performs similar checking on
individual data blocks to determine whether to transfer them or not.
You can control this with the -W or
--whole-file options, providing the value
yes or no:
# Tectia
$ scp --whole-file yes myfile server.example.com: Always transfer whole filesAs scp copies files, it prints information about its progress, including statistics about the file transfer. You can control this information with various options.
OpenSSH simply lets you suppress the statistics with its -q option:
# OpenSSH
$ scp -q myfile server.example.com:Tectia can likewise suppress statistics with the -Q option (Tectia).
# Tectia
$ scp -Q myfile server.example.com:but permits more control with the --statistics option:
# Tectia
$ scp --statistics no myfile server.example.com: Same as -Q option
$ scp --statistics simple myfile server.example.com: Minimal statistics
/home/smith/myfile | 4B | 4B/s | TOC: 00:00:01
$ scp --statistics yes myfile server.example.com: Full statistics
myfile | 4B | 4B/s | TOC: 00:00:01 | 100%To copy files securely, scp invokes
ssh internally. Therefore,
scp needs to know where the
ssh executable resides on disk. Normally, the
path to ssh is made known to
scp at compile time (by the compile-time flag
--prefix), but you can specify the path manually if
you like. [4.3.5.1]
For instance, you can test a new version of ssh
with an old version of scp. The command-line
option -S specifies the path:
$ scp -S /usr/alternative/bin/ssh myfile server.example.com:
Both OpenSSH and Tectia scp will print a usage message briefly describing all its options:
$ scp --help
You can get the same effect if you omit all arguments (OpenSSH) or use -h (Tectia). Tectia will also print its version number on request:
# Tectia
$ scp --version
$ scp -Vscp for OpenSSH has two undocumented options, -t and -f, for internal use. Most likely you will never need to use them explicitly. They inform scp of the direction of the copy: from the local to the remote machine, or from remote to local. The -t option means copying to a remote machine and -f means copying from a remote machine.
Whenever you invoke scp, it invisibly runs a second scp process on the remote host that includes either -t or -f on its command line. You can see this if you run scp in verbose mode. If copying from the local to the remote machine, you see:
$ scp -v myfile server.example.com:
Executing: host server.example.com, ..., command scp -v -t .
...On the other hand, if you copy from the remote to the local machine, you see:
$ scp -v server.example.com:myfile .
Executing: host server.example.com, ..., command scp -v -f .
...Again, it's likely you'll never use these options, but they're useful to know when reading scp's output in verbose mode.
You can set any client configuration keywords for scp using the -o option, exactly as for ssh. Additionally, OpenSSH lets you specify an alternative configuration file with -F. [7.1.2.1]
[115] We say "must," but technically you could specify a file as a destination in some cases. However, this behavior is probably not what you want. As your multiple files get copied into a single destination file, each is overwritten by the next!
[116] These limitations also are true when copying single files, but at least you see the erroneous result quickly. With directories, you can copy a hierarchy incorrectly and not notice.
[117] There's one degenerate case. If your copy occurs on a single machine, e.g., scp *.c mydir, the scp client doesn't necessarily check that mydir is a directory.