asciidoc/resolver/sftp.adoc

////
   Licensed to the Apache Software Foundation (ASF) under one
   or more contributor license agreements.  See the NOTICE file
   distributed with this work for additional information
   regarding copyright ownership.  The ASF licenses this file
   to you under the Apache License, Version 2.0 (the
   "License"); you may not use this file except in compliance
   with the License.  You may obtain a copy of the License at

     https://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing,
   software distributed under the License is distributed on an
   "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
   KIND, either express or implied.  See the License for the
   specific language governing permissions and limitations
   under the License.
////

= SFTP resolver

[]
|=======
|Tag|sftp
|Handle latest|yes
|Handle publish|yes
|=======

[*__since 1.4__*]

[ivysettings.resolvers.sftp]#This resolver can be used when your Ivy repository is located on a server accessible via SFTP.# The secured nature of SFTP and its widespread implementation on most *nix servers makes this resolver a very good candidate in an enterprise environment.

If your server supports SSH but not SFTP, there is also an link:../resolver/ssh{outfilesuffix}[SSH resolver].

Note that SFTP is also supported by VFS, so you can use a VFS resolver instead. The advantage of this resolver is that you have a better control over authentication, it can prompt for username/password credentials, or you can use private/public key authentication, which is not possible with the VFS resolver. When it prompts for username/password, it uses a Swing dialog, which is not possible in a headless environment. If you want to prompt for the credentials on the command line, use Ant input task, for example, before calling Ivy.

All necessary connection parameters can be set here via attributes, or via an OpenSSH-style config file specified by `sshConfig`.
However all attributes defined in the pattern URL of the resolver will have higher priority and will overwrite the values given here. To specify connection parameters in the pattern, you have to specify a full URL and not just a path as pattern.
e.g. `pattern="/path/to/my/repos/[artifact].[ext]"` will use all connection parameters from this class
e.g. `pattern="sftp://myserver.com/path/to/my/repos/[artifact].[ext]"` will use all parameters from the attributes with the exception of the host, which will be "myserver.com"
e.g. `pattern="sftp://user:geheim@myserver.com:8022/path/to/my/repos/[artifact].[ext]"` will use only the keyFile and keyFilePassword from the attributes (if needed). Rest will come from the URL.



Note that the authentication features of this resolver are exactly the same as the SSH resolver. Choosing between the two is often a matter of server implementation. If your server supports SFTP, usually it's preferable.

Internally this resolver relies on link:http://www.jcraft.com/jsch/[jsch] as SSH client, which is a popular Java SSH client, used for example in Eclipse.


== Attributes

This resolver shares the link:../settings/resolvers{outfilesuffix}#common[common attributes] of standard resolvers.

[options="header",cols="15%,50%,35%"]
|=======
|Attribute|Description|Required
|user|The username to provide as credential|No, defaults to username given on the patterns, or prompt if none is set
|userPassword|The password to provide as credential|No, defaults to password given on the patterns, or prompt if none is set
|keyFile|Path to the keyfile to use for authentication|No, defaults to username/password authentication
|keyFilePassword|the password used to protect the key file|No, will prompt for password if keyFile authentication is used and if it is password encrypted
|host|The host to connect to|No, defaults to host given on the patterns, fail if none is set
|port|The port to connect to|No, defaults to 22
|sshConfig|Path to an OpenSSH-style config file containing additional configuration|No
|=======


== Child elements


[options="header"]
|=======
|Element|Description|Cardinality
|ivy|defines a pattern for Ivy files, using the pattern attribute|0..n
|artifact|defines a pattern for artifacts, using the pattern attribute|1..n
|=======



== Example


[source, xml]
----

<sftp user="myuser" host="myhost.com">
  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
</sftp>

----

Will connect to myhost.com using myuser and prompt for the password.

'''


[source, xml]
----

<sftp user="${myuser}" userPassword="${my.password}" host="myhost.com">
  <ivy pattern="path/to/ivy/[module]/ivy.xml"/>
  <artifact pattern="path/to/[organisation]/[module]/[artifact].[ext]"/>
</sftp>

----

Will connect to myhost.com using user and password provided with Ivy variables.

'''


[source, xml]
----

<sftp>
  <ivy pattern="sftp://user:geheim@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
  <artifact pattern="sftp://user:secret@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
</sftp>

----

Will connect to yourserver.com on port 8022 with user 'user' and password 'geheim' for authentication for Ivy files, and to myserver.com on port 8022 using user 'user' and password 'secret' for the artifacts.

'''


[source, xml]
----

<sftp keyFile="path/to/key/file" keyFilePassword="${password}">
  <ivy pattern="sftp://user@yourserver.com:8022/path/to/repos/[module]/[revision]/ivy.xml"/>
  <artifact pattern="sftp://user@myserver.com:8022/path/to/my/repos/[artifact].[ext]"/>
</sftp>

----

Will connect to yourserver.com on port 8022 with user 'user' and use keyFile `path/to/key/file` for `keyFile` and the value of password variable for `keyFilePassword` authentication for Ivy files, and to myserver.com on port 8022 using user 'user' with the same keyFile/keyFilePassword pair for the artifacts.


[source, xml]
----

<sftp host="myhost" sshConfig="/path/to/.ssh/config">
  <ivy pattern="/path/to/ivy/[module]/ivy.xml"/>
  <artifact pattern="/path/to/[organisation]/[module]/[artifact].[ext]"/>
</ssh>

----

Will connect to the host named by myhost according to the config file in `/path/to/.ssh/config`, using the hostname, username, and optionally IdentityFile specified in the config section "Host myhost". For example, if the corresponding Host section contains "Hostname yourserver.com" and "User myremoteusername", it will connect to yourserver.com using username myremoteusername.