Repository files navigation

Thesftp-fs library provides support for SFTP NIO.2 file systems, allowing SFTP servers to be accessed in a similar way to local file systems.

If the SFTP file system library is available on the class path, it will register aFileSystemProvider for schemesftp. This allows you to create SFTP file systems using thenewFileSystem methods of classFileSystems. You can use classSFTPEnvironment to help create the environment maps for those methods:

SFTPEnvironmentenv =newSFTPEnvironment()        .withUsername(username)        .withUserInfo(userInfo);FileSystemfs =FileSystems.newFileSystem(URI.create("sftp://example.org"),env);

Credentials can be provided either through the URI or through the environment, as shown above. For security reasons the latter is preferred.

There are a few ways to provide credentials through the environment. The easiest way is to callwithUserInfo on anSFTPEnvironment instance with aUserInfo object to provide the password, and if necessary the passphrase. Thesftp-fs library provides classSimpleUserInfo to provide a fixed password and passphrase. Note that any prompt will be answered with "no". That means that you will most likely also need to set aHostKeyRepository by callingwithHostKeyRepository on anSFTPEnvironment instance to verify the host.

If theUserInfo object will only provide a fixed password and do nothing else, you can also callwithPassword on theSFTPEnvironment instance instead. This too most likely requires aHostKeyRepository to be set.

Instead of using a password, it's also possible to use other authentication methods using anIdentityRepository, which can be set by callingwithIdentityRepository on anSFTPEnvironment instance. The following code snippet shows how you can use pageant to authenticate:

SFTPEnvironmentenv =newSFTPEnvironment()        .withUsername(username)        .withIdentityRepository(newAgentIdentityRepository(newPageantConnector()));FileSystemfs =FileSystems.newFileSystem(URI.create("sftp://example.org"),env);

The default directory can be provided through the URI or trough the environment usingwithDefaultDirectory, as follows:

After a file system has been created,Paths can be created through the file system itself using itsgetPath method. As long as the file system is not closed, it's also possible to usePaths.get. Note that if the file system was created with credentials, the username must be part of the URL. For instance:

// created without credentialsPathpath1 =Paths.get(URI.create("sftp://example.org"));// created with credentialsPathpath2 =Paths.get(URI.create("sftp://username@example.org"));

If the username in the URI does not match the username used to create the file system, or if no file system has been created for the URI, a new file system will be created. This works likeCreating file systems. Since no environment can be provided this way, settings can still be provided throughSFTPEnvironment.setDefault and query parameters; see usages ofQueryParam andQueryParams for the possible query parameters. If creating a new file system fails, aFileSystemNotFoundException will be thrown.

SFTP file systems fully support read-access to the following attributes:

• Attributes defined inBasicFileAttributeView andBasicFileAttributes, available both with and without prefixesbasic: orposix:.
• Attributes defined inFileOwnerAttributeView, available with prefixesowner: orposix:.
• Attributes defined inPosixFileAttributeView andPosixFileAttributes, available with prefixposix:.

It's not possible to set the last access time or creation time, either through one of the file attribute views or through a file system. Attempting to do so will result in anUnsupportedOperationException. All other attributes are supported, although when setting the owner or group the name must be the UID/GID.

When callinggetAttribute on a file store, the following attributes are supported:

• totalSpace: returns the same value as thegetTotalSpace method.
• usableSpace: returns the same value as thegetUsableSpace method.
• unallocatedSpace: returns the same value as thegetUnallocatedSpace method.

These values are only supported by SFTP servers that support thestatvfs@openssh.com extension. If this extension is not supported, these methods will all returnLong.MAX_VALUE.

There is no support forFileStoreAttributeView. CallinggetFileStoreAttributeView on a file store will simply returnnull.

Not all SFTP servers support the same set of error codes. Because of this, most methods may not throw the correct exception (NoSuchFileException,AccessDeniedException, etc).

To allow this behaviour to be modified, classSFTPEnvironment has methodwithFileSystemExceptionFactory that allows you to specify a customFileSystemExceptionFactory implementation which will be used to create exceptions based on the reply code and string of the command that triggered the error. By default, an instance of classDefaultFileSystemExceptionFactory is used.

The SFTP protocol is fundamentally not thread safe. To overcome this limitation, SFTP file systems maintain multiple connections to SFTP servers. The number of connections determines the number of concurrent operations that can be executed. If all connections are busy, a new operation will block until a connection becomes available. ClassSFTPEnvironment has methodwithPoolConfig that allows you to configure the connection pool:

• The initial pool size - the number of connections that are created when an SFTP file system is created. The default is1.
• The maximum pool size - the maximum number of concurrent operations. The default is5.
• The maximum wait time - this determines how long to wait until a connection is available. The default is to wait indefinitely.
• The maximum time that connections can be idle. The default is indefinitely.

When a stream or channel is opened for reading or writing, the connection will block because it will wait for the download or upload to finish. This will not occur until the stream or channel is closed. It is therefore advised to close streams and channels as soon as possible.

Because SFTP file systems use multiple connections to an SFTP server, it's possible that one or more of these connections become stale. ClassSFTPFileSystemProvider has static methodkeepAlive that, if given an instance of an SFTP file system, will send a keep-alive signal over each of its idle connections. You should ensure that this method is called on a regular interval. An alternative is to set a maximum idle time (seeThread safety).

SFTP file systems knows the following limitations:

• All paths use/ as separator./ is not allowed inside file or directory names.
• File attributes cannot be set when creating files or directories.
• Symbolic links can be read and traversed, but not created.
• There is no support for hard links.
• Files can be marked as executable if the SFTP server indicates it is. That does not mean the file can be executed in the local JVM.
• SeekableByteChannel is supported because it's used byFiles.createFile. However, these channels do not support seeking specific positions or truncating.
• FileSystem.getFileStores() will only return aFileStore for the root path, even if the SFTP server actually has several mount points.
• AlthoughFileSystemProvider.getFileStore(Path) will return aFileStore for the actualPath, its name will always be/, even if the file or directory is located on a different mount point.
• There is no support forUserPrincipalLookupService.
• There is no support forWatchService.