Package org.apache.sshd.client.config.hosts

Class HostConfigEntry

java.lang.Object
org.apache.sshd.client.config.hosts.HostPatternsHolder
org.apache.sshd.client.config.hosts.HostConfigEntry
All Implemented Interfaces:
MutableUserHolder, UsernameHolder
public class HostConfigEntry extends HostPatternsHolder implements MutableUserHolder
Represents an entry in the client's configuration file as defined by the ssh_config configuration file format
Author:
Apache MINA SSHD Project
See Also:

  • Field Details

    • STD_CONFIG_FILENAME

      public static final String STD_CONFIG_FILENAME
      Standard OpenSSH config file name
      See Also:

    • HOST_CONFIG_PROP

      public static final String HOST_CONFIG_PROP
      See Also:

    • HOST_NAME_CONFIG_PROP

      public static final String HOST_NAME_CONFIG_PROP
      See Also:

    • PORT_CONFIG_PROP

      public static final String PORT_CONFIG_PROP
      See Also:

    • USER_CONFIG_PROP

      public static final String USER_CONFIG_PROP
      See Also:

    • PROXY_JUMP_CONFIG_PROP

      public static final String PROXY_JUMP_CONFIG_PROP
      See Also:

    • IDENTITY_FILE_CONFIG_PROP

      public static final String IDENTITY_FILE_CONFIG_PROP
      See Also:

    • EXCLUSIVE_IDENTITIES_CONFIG_PROP

      public static final String EXCLUSIVE_IDENTITIES_CONFIG_PROP
      Use only the identities specified in the host entry (if any)
      See Also:

    • DEFAULT_EXCLUSIVE_IDENTITIES

      public static final boolean DEFAULT_EXCLUSIVE_IDENTITIES
      See Also:

    • IDENTITY_AGENT

      public static final String IDENTITY_AGENT
      The IdentityAgent configuration. If not set in the HostConfigEntry, the value of this property is null, which means that a default SSH agent is to be used, if it is running. Other values defined by OpenSSH are:
        none
        No SHH agent is to be used at all, even if one is running.
        SSH_AUTH_SOCK
        The SSH agent listening on the Unix domain socket given by the environment variable SSH_AUTH_SOCK shall be used. If the environment variable is not set, no SSH agent is used.
        other
        For OpenSSH, the value shall resolve to the file name of a Unix domain socket to use to connect to an SSH agent.
      See Also:

    • EXPLICIT_PROPERTIES

      public static final NavigableSet<String> EXPLICIT_PROPERTIES
      A case insensitive NavigableSet of the properties that receive special handling

    • MULTI_VALUE_SEPARATORS

      public static final String MULTI_VALUE_SEPARATORS
      See Also:

    • PATH_MACRO_CHAR

      public static final char PATH_MACRO_CHAR
      See Also:

    • LOCAL_HOME_MACRO

      public static final char LOCAL_HOME_MACRO
      See Also:

    • LOCAL_USER_MACRO

      public static final char LOCAL_USER_MACRO
      See Also:

    • LOCAL_HOST_MACRO

      public static final char LOCAL_HOST_MACRO
      See Also:

    • REMOTE_HOST_MACRO

      public static final char REMOTE_HOST_MACRO
      See Also:

    • REMOTE_USER_MACRO

      public static final char REMOTE_USER_MACRO
      See Also:

    • REMOTE_PORT_MACRO

      public static final char REMOTE_PORT_MACRO
      See Also:

  • Constructor Details

    • HostConfigEntry

      public HostConfigEntry()

    • HostConfigEntry

      public HostConfigEntry(String pattern, String host, int port, String username)

    • HostConfigEntry

      public HostConfigEntry(String pattern, String host, int port, String username, String proxyJump)

  • Method Details

    • getHost

      public String getHost()
      Returns:
      The pattern(s) represented by this entry

    • setHost

      public void setHost(String host)

    • setHost

      public void setHost(Collection<String> patterns)

    • getHostName

      public String getHostName()
      Returns:
      The effective host name to connect to if the pattern matches

    • setHostName

      public void setHostName(String hostName)

    • resolveHostName

      public String resolveHostName(String originalHost)

    • getPort

      public int getPort()
      Returns:
      A port override - if positive

    • setPort

      public void setPort(int port)

    • resolvePort

      public int resolvePort(int originalPort)
      Resolves the effective port to use
      Parameters:
      originalPort - The original requested port
      Returns:
      If the host entry port is positive, then it is used, otherwise the original requested port
      See Also:

    • getUsername

      public String getUsername()
      Specified by:
      getUsername in interface UsernameHolder
      Returns:
      A username override - if not null/empty

    • setUsername

      public void setUsername(String username)
      Specified by:
      setUsername in interface MutableUserHolder

    • resolveUsername

      public String resolveUsername(String originalUser)
      Resolves the effective username
      Parameters:
      originalUser - The original requested username
      Returns:
      If the configured host entry username is not null/empty then it is used, otherwise the original one.
      See Also:

    • getProxyJump

      public String getProxyJump()
      Returns:
      the host to use as a proxy

    • setProxyJump

      public void setProxyJump(String proxyJump)

    • resolveProxyJump

      public String resolveProxyJump(String originalProxyJump)
      Resolves the effective proxyJump
      Parameters:
      originalProxyJump - The original requested proxyJump
      Returns:
      If the configured host entry proxyJump is not null/empty then it is used, otherwise the original one.
      See Also:

    • getIdentities

      public Collection<String> getIdentities()
      Returns:
      The current identities file paths - may be null/empty

    • addIdentity

      public void addIdentity(Path path)
      Parameters:
      path - A Path to a file that contains an identity key - never null

    • addIdentity

      public void addIdentity(String id)
      Adds a path to an identity file
      Parameters:
      id - The identity path to add - never null

    • setIdentities

      public void setIdentities(Collection<String> identities)

    • isIdentitiesOnly

      public boolean isIdentitiesOnly()
      Returns:
      true if must use only the identities in this entry

    • setIdentitiesOnly

      public void setIdentitiesOnly(boolean identitiesOnly)

    • getProperties

      public Map<String,String> getProperties()
      Returns:
      A Map of extra properties that have been read - may be null/empty, or even contain some values that have been parsed and set as members of the entry (e.g., host, port, etc.). Note: multi-valued keys use a comma-separated list of values

    • getProperty

      public String getProperty(String name)
      Parameters:
      name - Property name - never null/empty
      Returns:
      Property value or null if no such property
      See Also:

    • getProperty

      public String getProperty(String name, String defaultValue)
      Parameters:
      name - Property name - never null/empty
      defaultValue - Default value to return if no such property
      Returns:
      The property value or the default one if no such property

    • processGlobalValues

      public boolean processGlobalValues(HostConfigEntry globalEntry)
      Updates the values that are not already configured with those from the global entry
      Parameters:
      globalEntry - The global entry - ignored if null or same reference as this entry
      Returns:
      true if anything updated

    • updateGlobalProperties

      public Map<String,String> updateGlobalProperties(Map<String,String> props)
      Sets all the properties for which no current value exists in the entry
      Parameters:
      props - The global properties - ignored if null/empty
      Returns:
      A Map of the updated properties

    • updateGlobalIdentities

      public boolean updateGlobalIdentities(Collection<String> ids)
      Parameters:
      ids - Global identities - ignored if null/empty or already have configured identities
      Returns:
      true if updated identities

    • updateGlobalUserName

      public boolean updateGlobalUserName(String user)
      Parameters:
      user - The global user name - ignored if null/empty or already have a configured user
      Returns:
      true if updated the username

    • updateGlobalHostName

      public boolean updateGlobalHostName(String name)
      Parameters:
      name - The global host name - ignored if null/empty or already have a configured target host
      Returns:
      true if updated the target host

    • updateGlobalPort

      public boolean updateGlobalPort(int portValue)
      Parameters:
      portValue - The global port value - ignored if not positive or already have a configured port
      Returns:
      true if updated the port value

    • updateGlobalIdentityOnly

      public boolean updateGlobalIdentityOnly(boolean identitiesOnly)
      Parameters:
      identitiesOnly - Whether to use only the identities in this entry. Ignored if already set
      Returns:
      true if updated the option value

    • processProperty

      public void processProperty(String name, Collection<String> valsList, boolean ignoreAlreadyInitialized)
      Parameters:
      name - Property name - never null/empty
      valsList - The available values for the property
      ignoreAlreadyInitialized - If false and one of the "known" properties is encountered then throws an exception
      Throws:
      IllegalArgumentException - If an existing value is overwritten and ignoreAlreadyInitialized is false (except for IDENTITY_FILE_CONFIG_PROP which is cumulative
      See Also:

    • appendPropertyValue

      public String appendPropertyValue(String name, String value)
      Appends a value using a comma to an existing one. If no previous value then same as calling setProperty(String, String).
      Parameters:
      name - Property name - never null/empty
      value - The value to be appended - ignored if null/empty
      Returns:
      The value before appending - null if no previous value

    • setProperty

      public String setProperty(String name, String value)
      Sets / Replaces the property value
      Parameters:
      name - Property name - never null/empty
      value - Property value - if null/empty then removeProperty(String) is called
      Returns:
      The previous property value - null if no such name

    • removeProperty

      public String removeProperty(String name)
      Parameters:
      name - Property name - never null/empty
      Returns:
      The removed property value - null if no such property name

    • setProperties

      public void setProperties(Map<String,String> properties)
      Parameters:
      properties - The properties to set - if null then an empty map is effectively set. Note: it is highly recommended to use a case insensitive key mapper.

    • append

      public <A extends Appendable> A append(A sb) throws IOException
      Throws:
      IOException

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • appendNonEmptyPort

      public static <A extends Appendable> A appendNonEmptyPort(A sb, String name, int port) throws IOException
      Type Parameters:
      A - The Appendable type
      Parameters:
      sb - The target appender
      name - The property name - never null/empty
      port - The port value - ignored if non-positive
      Returns:
      The target appender after having appended (or not) the value
      Throws:
      IOException - If failed to append the requested data
      See Also:

    • appendNonEmptyProperties

      public static <A extends Appendable> A appendNonEmptyProperties(A sb, Map<String,?> props) throws IOException
      Appends the extra properties - while skipping the EXPLICIT_PROPERTIES ones
      Type Parameters:
      A - The Appendable type
      Parameters:
      sb - The target appender
      props - The Map of properties - ignored if null/empty
      Returns:
      The target appender after having appended (or not) the value
      Throws:
      IOException - If failed to append the requested data
      See Also:

    • appendNonEmptyProperty

      public static <A extends Appendable> A appendNonEmptyProperty(A sb, String name, Object value) throws IOException
      Type Parameters:
      A - The Appendable type
      Parameters:
      sb - The target appender
      name - The property name - never null/empty
      value - The property value - ignored if null. Note: if the string representation of the value contains any commas, they are assumed to indicate a multi-valued property which is broken down to individual lines - one per value.
      Returns:
      The target appender after having appended (or not) the value
      Throws:
      IOException - If failed to append the requested data
      See Also:

    • appendNonEmptyValues

      public static <A extends Appendable> A appendNonEmptyValues(A sb, String name, Object... values) throws IOException
      Type Parameters:
      A - The Appendable type
      Parameters:
      sb - The target appender
      name - The property name - never null/empty
      values - The values to be added - one per line - ignored if null/empty
      Returns:
      The target appender after having appended (or not) the value
      Throws:
      IOException - If failed to append the requested data
      See Also:

    • appendNonEmptyValues

      public static <A extends Appendable> A appendNonEmptyValues(A sb, String name, Collection<?> values) throws IOException
      Type Parameters:
      A - The Appendable type
      Parameters:
      sb - The target appender
      name - The property name - never null/empty
      values - The values to be added - one per line - ignored if null/empty
      Returns:
      The target appender after having appended (or not) the value
      Throws:
      IOException - If failed to append the requested data

    • toHostConfigEntryResolver

      public static HostConfigEntryResolver toHostConfigEntryResolver(Collection<? extends HostConfigEntry> entries)
      Parameters:
      entries - The entries - ignored if null/empty
      Returns:
      A HostConfigEntryResolver wrapper using the entries

    • normalizeEntry

      public static HostConfigEntry normalizeEntry(HostConfigEntry entry, String host, int port, String username, String proxyJump) throws IOException
      Parameters:
      entry - The original entry - ignored if null
      host - The original host name / address
      port - The original port
      username - The original user name
      proxyJump - And optional proxy jump setting
      Returns:
      A cloned entry whose values are resolved - including expanding macros in the identities files
      Throws:
      IOException - If failed to normalize the entry
      See Also:

    • resolveHostName

      public static String resolveHostName(String originalName, String entryName)
      Resolves the effective target host
      Parameters:
      originalName - The original requested host
      entryName - The configured host
      Returns:
      If the configured host entry is not null/empty then it is used, otherwise the original one.

    • resolveUsername

      public static String resolveUsername(String originalUser, String entryUser)
      Resolves the effective username
      Parameters:
      originalUser - The original requested username
      entryUser - The configured host entry username
      Returns:
      If the configured host entry username is not null/empty then it is used, otherwise the original one.

    • resolvePort

      public static int resolvePort(int originalPort, int entryPort)
      Resolves the effective port to use
      Parameters:
      originalPort - The original requested port
      entryPort - The configured host entry port
      Returns:
      If the host entry port is positive, then it is used, otherwise the original requested port

    • resolveProxyJump

      public static String resolveProxyJump(String originalProxyJump, String entryProxyJump)
      Resolves the effective proxyJump
      Parameters:
      originalProxyJump - The original requested proxyJump
      entryProxyJump - The configured host entry proxyJump
      Returns:
      If the configured host entry proxyJump is not null/empty then it is used, otherwise the original one.

    • readHostConfigEntries

      public static List<HostConfigEntry> readHostConfigEntries(Path path, OpenOption... options) throws IOException
      Throws:
      IOException

    • readHostConfigEntries

      public static List<HostConfigEntry> readHostConfigEntries(URL url) throws IOException
      Throws:
      IOException

    • readHostConfigEntries

      public static List<HostConfigEntry> readHostConfigEntries(InputStream inStream, boolean okToClose) throws IOException
      Throws:
      IOException

    • readHostConfigEntries

      public static List<HostConfigEntry> readHostConfigEntries(Reader rdr, boolean okToClose) throws IOException
      Throws:
      IOException

    • readHostConfigEntries

      public static List<HostConfigEntry> readHostConfigEntries(BufferedReader rdr) throws IOException
      Reads configuration entries
      Parameters:
      rdr - The BufferedReader to use
      Returns:
      The List of read HostConfigEntry-ies
      Throws:
      IOException - If failed to parse the read configuration

    • findBestMatch

      public static HostConfigEntry findBestMatch(Collection<? extends HostConfigEntry> matches)
      Finds the best match out of the given ones.
      Parameters:
      matches - The available matches - ignored if null/empty
      Returns:
      The best match or null if no matches or no best match found
      See Also:

    • findBestMatch

      public static HostConfigEntry findBestMatch(Iterable<? extends HostConfigEntry> matches)
      Finds the best match out of the given ones.
      Parameters:
      matches - The available matches - ignored if null/empty
      Returns:
      The best match or null if no matches or no best match found
      See Also:

    • findBestMatch

      public static HostConfigEntry findBestMatch(Iterator<? extends HostConfigEntry> matches)
      Finds the best match out of the given ones. The best match is defined as one whose pattern is as specific as possible (if more than one match is available). I.e., a non-global match is preferred over global one, and a match with no wildcards is preferred over one with such a pattern.
      Parameters:
      matches - The available matches - ignored if null/empty
      Returns:
      The best match or null if no matches or no best match found
      See Also:

    • updateEntriesList

      public static List<HostConfigEntry> updateEntriesList(List<HostConfigEntry> entries, HostConfigEntry curEntry)

    • writeHostConfigEntries

      public static void writeHostConfigEntries(Path path, Collection<? extends HostConfigEntry> entries, OpenOption... options) throws IOException
      Throws:
      IOException

    • writeHostConfigEntries

      public static void writeHostConfigEntries(OutputStream outputStream, boolean okToClose, Collection<? extends HostConfigEntry> entries) throws IOException
      Throws:
      IOException

    • appendHostConfigEntries

      public static <A extends Appendable> A appendHostConfigEntries(A sb, Collection<? extends HostConfigEntry> entries) throws IOException
      Throws:
      IOException

    • parseConfigValue

      public static List<String> parseConfigValue(String value)
      Checks if this is a multi-value - allow space and comma
      Parameters:
      value - The value - ignored if null/empty (after trimming)
      Returns:
      A List of the encountered values

    • resolveIdentityFilePath

      public static String resolveIdentityFilePath(String id, String host, int port, String username) throws IOException
      Throws:
      IOException

    • getDefaultHostConfigFile

      public static Path getDefaultHostConfigFile()
      Returns:
      The default Path location of the OpenSSH hosts entries configuration file