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

Class HostConfigEntry

    • Field Detail

      • STD_CONFIG_FILENAME

        public static final java.lang.String STD_CONFIG_FILENAME
        Standard OpenSSH config file name
        See Also:
        Constant Field Values

      • HOST_CONFIG_PROP

        public static final java.lang.String HOST_CONFIG_PROP
        See Also:
        Constant Field Values

      • HOST_NAME_CONFIG_PROP

        public static final java.lang.String HOST_NAME_CONFIG_PROP
        See Also:
        Constant Field Values

      • PORT_CONFIG_PROP

        public static final java.lang.String PORT_CONFIG_PROP
        See Also:
        Constant Field Values

      • USER_CONFIG_PROP

        public static final java.lang.String USER_CONFIG_PROP
        See Also:
        Constant Field Values

      • PROXY_JUMP_CONFIG_PROP

        public static final java.lang.String PROXY_JUMP_CONFIG_PROP
        See Also:
        Constant Field Values

      • IDENTITY_FILE_CONFIG_PROP

        public static final java.lang.String IDENTITY_FILE_CONFIG_PROP
        See Also:
        Constant Field Values

      • EXCLUSIVE_IDENTITIES_CONFIG_PROP

        public static final java.lang.String EXCLUSIVE_IDENTITIES_CONFIG_PROP
        Use only the identities specified in the host entry (if any)
        See Also:
        Constant Field Values

      • DEFAULT_EXCLUSIVE_IDENTITIES

        public static final boolean DEFAULT_EXCLUSIVE_IDENTITIES
        See Also:
        Constant Field Values

      • IDENTITY_AGENT

        public static final java.lang.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:
        Constant Field Values

      • EXPLICIT_PROPERTIES

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

      • MULTI_VALUE_SEPARATORS

        public static final java.lang.String MULTI_VALUE_SEPARATORS
        See Also:
        Constant Field Values

      • host

        private java.lang.String host

      • hostName

        private java.lang.String hostName

      • port

        private int port

      • username

        private java.lang.String username

      • proxyJump

        private java.lang.String proxyJump

      • exclusiveIdentites

        private java.lang.Boolean exclusiveIdentites

      • identities

        private java.util.Collection<java.lang.String> identities

      • properties

        private java.util.Map<java.lang.String,​java.lang.String> properties

    • Constructor Detail

      • HostConfigEntry

        public HostConfigEntry()

      • HostConfigEntry

        public HostConfigEntry​(java.lang.String pattern,
                       java.lang.String host,
                       int port,
                       java.lang.String username)

      • HostConfigEntry

        public HostConfigEntry​(java.lang.String pattern,
                       java.lang.String host,
                       int port,
                       java.lang.String username,
                       java.lang.String proxyJump)

    • Method Detail

      • getHost

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

      • setHost

        public void setHost​(java.lang.String host)

      • setHost

        public void setHost​(java.util.Collection<java.lang.String> patterns)

      • getHostName

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

      • setHostName

        public void setHostName​(java.lang.String hostName)

      • resolveHostName

        public java.lang.String resolveHostName​(java.lang.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:
        resolvePort(int, int)

      • getUsername

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

      • resolveUsername

        public java.lang.String resolveUsername​(java.lang.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:
        resolveUsername(String)

      • getProxyJump

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

      • setProxyJump

        public void setProxyJump​(java.lang.String proxyJump)

      • resolveProxyJump

        public java.lang.String resolveProxyJump​(java.lang.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:
        resolveUsername(String)

      • getIdentities

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

      • addIdentity

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

      • addIdentity

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

      • setIdentities

        public void setIdentities​(java.util.Collection<java.lang.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 java.util.Map<java.lang.String,​java.lang.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 java.lang.String getProperty​(java.lang.String name)
        Parameters:
        name - Property name - never null/empty
        Returns:
        Property value or null if no such property
        See Also:
        getProperty(String, String)

      • getProperty

        public java.lang.String getProperty​(java.lang.String name,
                                    java.lang.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 java.util.Map<java.lang.String,​java.lang.String> updateGlobalProperties​(java.util.Map<java.lang.String,​java.lang.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​(java.util.Collection<java.lang.String> ids)
        Parameters:
        ids - Global identities - ignored if null/empty or already have configured identities
        Returns:
        true if updated identities

      • updateGlobalUserName

        public boolean updateGlobalUserName​(java.lang.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​(java.lang.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​(java.lang.String name,
                            java.util.Collection<java.lang.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:
        java.lang.IllegalArgumentException - If an existing value is overwritten and ignoreAlreadyInitialized is false (except for IDENTITY_FILE_CONFIG_PROP which is cumulative
        See Also:
        HOST_NAME_CONFIG_PROP, PORT_CONFIG_PROP, USER_CONFIG_PROP, IDENTITY_FILE_CONFIG_PROP

      • appendPropertyValue

        public java.lang.String appendPropertyValue​(java.lang.String name,
                                            java.lang.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 java.lang.String setProperty​(java.lang.String name,
                                    java.lang.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 java.lang.String removeProperty​(java.lang.String name)
        Parameters:
        name - Property name - never null/empty
        Returns:
        The removed property value - null if no such property name

      • setProperties

        public void setProperties​(java.util.Map<java.lang.String,​java.lang.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 java.lang.Appendable> A append​(A sb)
                                          throws java.io.IOException
        Throws:
        java.io.IOException

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • appendNonEmptyPort

        public static <A extends java.lang.Appendable> A appendNonEmptyPort​(A sb,
                                                                    java.lang.String name,
                                                                    int port)
                                                             throws java.io.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:
        java.io.IOException - If failed to append the requested data
        See Also:
        appendNonEmptyProperty(Appendable, String, Object)

      • appendNonEmptyProperties

        public static <A extends java.lang.Appendable> A appendNonEmptyProperties​(A sb,
                                                                          java.util.Map<java.lang.String,​?> props)
                                                                   throws java.io.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:
        java.io.IOException - If failed to append the requested data
        See Also:
        appendNonEmptyProperty(Appendable, String, Object)

      • appendNonEmptyProperty

        public static <A extends java.lang.Appendable> A appendNonEmptyProperty​(A sb,
                                                                        java.lang.String name,
                                                                        java.lang.Object value)
                                                                 throws java.io.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:
        java.io.IOException - If failed to append the requested data
        See Also:
        appendNonEmptyValues(Appendable, String, Object...)

      • appendNonEmptyValues

        public static <A extends java.lang.Appendable> A appendNonEmptyValues​(A sb,
                                                                      java.lang.String name,
                                                                      java.lang.Object... values)
                                                               throws java.io.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:
        java.io.IOException - If failed to append the requested data
        See Also:
        appendNonEmptyValues(Appendable, String, Collection)

      • appendNonEmptyValues

        public static <A extends java.lang.Appendable> A appendNonEmptyValues​(A sb,
                                                                      java.lang.String name,
                                                                      java.util.Collection<?> values)
                                                               throws java.io.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:
        java.io.IOException - If failed to append the requested data

      • resolveHostName

        public static java.lang.String resolveHostName​(java.lang.String originalName,
                                               java.lang.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 java.lang.String resolveUsername​(java.lang.String originalUser,
                                               java.lang.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 java.lang.String resolveProxyJump​(java.lang.String originalProxyJump,
                                                java.lang.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 java.util.List<HostConfigEntry> readHostConfigEntries​(java.nio.file.Path path,
                                                                    java.nio.file.OpenOption... options)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException

      • readHostConfigEntries

        public static java.util.List<HostConfigEntry> readHostConfigEntries​(java.net.URL url)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException

      • readHostConfigEntries

        public static java.util.List<HostConfigEntry> readHostConfigEntries​(java.io.InputStream inStream,
                                                                    boolean okToClose)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException

      • readHostConfigEntries

        public static java.util.List<HostConfigEntry> readHostConfigEntries​(java.io.Reader rdr,
                                                                    boolean okToClose)
                                                             throws java.io.IOException
        Throws:
        java.io.IOException

      • readHostConfigEntries

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

      • findBestMatch

        public static HostConfigEntry findBestMatch​(java.util.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(Iterator)

      • findBestMatch

        public static HostConfigEntry findBestMatch​(java.lang.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(Iterator)

      • findBestMatch

        public static HostConfigEntry findBestMatch​(java.util.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:
        HostPatternsHolder.isSpecificHostPattern(String)

      • writeHostConfigEntries

        public static void writeHostConfigEntries​(java.nio.file.Path path,
                                          java.util.Collection<? extends HostConfigEntry> entries,
                                          java.nio.file.OpenOption... options)
                                   throws java.io.IOException
        Throws:
        java.io.IOException

      • writeHostConfigEntries

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

      • appendHostConfigEntries

        public static <A extends java.lang.Appendable> A appendHostConfigEntries​(A sb,
                                                                         java.util.Collection<? extends HostConfigEntry> entries)
                                                                  throws java.io.IOException
        Throws:
        java.io.IOException

      • parseConfigValue

        public static java.util.List<java.lang.String> parseConfigValue​(java.lang.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 java.lang.String resolveIdentityFilePath​(java.lang.String id,
                                                       java.lang.String host,
                                                       int port,
                                                       java.lang.String username)
                                                throws java.io.IOException
        Throws:
        java.io.IOException

      • appendUserHome

        public static java.lang.StringBuilder appendUserHome​(java.lang.StringBuilder sb)

      • appendUserHome

        public static java.lang.StringBuilder appendUserHome​(java.lang.StringBuilder sb,
                                                     java.nio.file.Path userHome)

      • appendUserHome

        public static java.lang.StringBuilder appendUserHome​(java.lang.StringBuilder sb,
                                                     java.lang.String userHome)

      • getDefaultHostConfigFile

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