<commit_before>
RunDeck Plugins
===========

Plugins for RunDeck contain new Providers for some of the Services used by
the RunDeck core.

RunDeck comes with some built-in providers for these services, but Plugins
let you write your own, or use third-party implementations.

RunDeck currently comes installed with a few useful plugins: script-plugin and 
stub-plugin.  See [Pre-installed plugins](#pre-installed-plugins) for more info.

## Installing Plugins

Installation of plugins is simple:

Put the plugin file, such as `plugin.jar` or `some-plugin.zip`, into the RunDeck 
server's libext dir:

    cp some-plugin.zip $RDECK_BASE/libext

The plugin is now enabled, and any providers it defines can be used by nodes
or projects.

The RunDeck server does not have to be restarted.

## Uninstalling or Updating Plugins

You can simply remove the plugin files from `$RDECK_BASE/libext` to uninstall
them.

You can overwrite an old plugin with a newer version to update it.

## About Plugins

Plugins are files that contain one or more Service Provider implementations. Each
plugin file could contain multiple Providers for different types of services,
however typically each plugin file would contain only providers related in some
fashion.

RunDeck includes a number of "built-in" providers, as well as a few 
"included" plugin files.

In this document "plugin" and "provider" are used somewhat interchangably. When 
referring to an actual file containing the provider implementations we will say
"plugin file".

![RunDeck Providers and Plugin Files](figures/fig1102.png)

## Types of Plugins

RunDeck supports several different types of plugins to perform different kinds 
of services.

### Node Execution Plugins

These plugins define ways of executing commands on nodes, and copying files to nodes.  

More information:

* Configuration: [Node Execution Services](#node-execution-services)
* Lifecycle: [When Node Execution Service providers are invoked](#when-node-execution-service-providers-are-invoked)
* Built-in Providers: [Node Execution services](#node-execution-services-1)
* Included Plugins: [Pre-installed plugins](#pre-installed-plugins)

### Resource Model Source Plugins

These plugins define mechanisms for retrieving Resource Model information from a
specific kind of source (such as a URL, file, or set of files in a directory).

More information:

* Configuration: [Resource Model Sources](#resource-model-sources)
* Built-in Providers: [Resource Model Sources](#resource-model-sources-1)

### Resource Format Plugins

These plugins define parsers and generators for different document formats, and
are used by the Resource Model Source Plugins, as well as other parts of the
RunDeck system.

More information:

* Configuration: [Resource Format Generators and Parsers](#resource-format-generators-and-parsers)
* Built-in Providers: [Resource Format services](#resource-format-services)

## About Services and Providers

The RunDeck core makes use of several different "Services" that provide
functionality for the different steps necessary to execute workflows, jobs, 
and commands across multiple nodes.

Each Service makes use of "Providers". Each Provider has a unique "Provider Name"
that is used to identify it, and most Services have default Providers unless
you specify different ones to use.

![RunDeck Services and Providers](figures/fig1101.png)

Services fall into different categories, which determine how and where they are used.

*Service Categories*:

1. **Node Execution services** - providers of these services operate in the context of a single Node definition, and
  can be configured at Node scope or higher:

    1. Node Executor - these providers define ways of executing a command on a Node (local or remote)
    2. File Copier - these providers define ways of copying files to a Node.

2. **Project services**

    1. Resource Model Source - (aka "Resource Providers") these define ways of retrieving Node resources for a Project 

3. **Global services** (framework level)

    1. Resource Format Parser - these define document format parsers
    2. Resource Format Generators - these define document format generators

Specifics of how providers of these plugins work is listed below.

RunDeck Plugins can contain more than one Provider.

## Using Providers

### Node Execution Services

The two *Node services*, Node Executor and File Copier, are both configured similarly.
They are configured for particular nodes on a node-specific basis,
or set as a default provider for a project or for the system.

If multiple providers are defined the most specific definition takes precedence
in this order:

1. Node specific
2. Project scope
3. Framework scope

#### Node Specific

To enable a provider for a node, add an attribute to the node definition.

*Node Executor provider attributes*:

`node-executor`

:    specifies the provider name for a non-local node.

`local-node-executor`

:    specifies the provider name for the local (server) node.


*FileCopier provider attributes*:

`file-copier`

:    specifies the provider by name for a non-local node.

`local-file-copier`

:    specifies the provider by name for the local (server) node.

Example Node in YAML specifying `stub` NodeExecutor and FileCopier:

    remotehost:
        hostname: remotehost
        node-executor: stub
        file-copier: stub

#### Project or Framework Scope

*Node Executor*

You can define the default connection providers to use for nodes at either the Project or
Framework scope (or both).  To do so, configure any of the following properties
in the `project.properties` or the `framework.properties` files.  

`service.NodeExecutor.default.provider`

:   Specifies the default NodeExecutor provider for remote nodes

`service.NodeExecutor.default.local.provider`

:   Specifies the default Node Executor provider for the  local node.

*File Copier*

`service.FileCopier.default.provider`

:   Specifies the default File Copier provider for remote nodes.

`service.FileCopier.default.local.provider`

:   Specifies the default File Copier provider for the local node.

Example `project.properties` to set default local providers to `stub`:

    service.NodeExecutor.default.local.provider=stub
    service.FileCopier.default.local.provider=stub

### Resource Model Sources

The *Resource Model Sources* providers can be configured for a single project 
in the `project.properties` file.

You can define multiple Resource Model Sources for the project, and can mix and match
the specific providers depending on your needs.

When you define multiple Source providers in a project, then the resulting set of Nodes will 
effectively be a merge of all the sources, in the order in which they are declared. This
means that if two or more Sources provide a definition of a node with the same name, then
the definition from lowest Source in the list will be used.

The order that the providers are loaded (and thus the nodes are merged) is:

1. `project.resources.file`: A File Model Source with default configuration.
2. `project.resources.url`: A URL Model Source with default configuration. (optional)
3. All `resources.source.N` configurations in order starting at 1

#### Resource Model Source configuration

The `project.properties` file for each project allows you to configure the Resource Model Sources in these ways:

* Define `project.resources.file` - this file path is used as a File Source path, with *autogeneration* and *includeServerNode* both true.
* Define `project.resources.url` - this URL is used as a URL Source url, with caching enabled

You may also define a list of more sources in this way:

Starting at index `1`, define these properties for your Source numbered `N`:

    resources.source.N.type=<provider-name>
    resources.source.N.config.<property>=<value>
    resources.source.N.config.<property2>=<value2>
    ...

Using one of the available Resource Model Source provider names for the `<provider-name>` value. For each Resource Model Source provider, 
you can specify the configuration properties for the source.

Example project.properties configuration of a default File provider, and two other providers:

    project.resources.file=/home/rundeck/projects/example/etc/resources.xml
    
    resources.source.1.type=url
    resources.source.1.url=http://server/nodes.yaml
    
    resources.source.2.type=directory
    resources.source.2.directory=/home/rundeck/projects/example/resources

### Resource Format Generators and Parsers

Resource Format Generators and Parsers define support for file formats that can
be generated from or parsed into a set of Resource Node definitions.

These are used by other parts of the system, such as the Resource Model Sources.

There is no configuration necessary to use these providers, however the specific
Provider Name that each generator and parser defines has to be known in order
to make use of the provider.  The specific Provider Name is used as the 
"format name" when you want to use the parser or generator.

For example, to enable a particular Resource Format parser to be used by a File
Resource Model Source (see [File Resource Model Source Configuration](#file-resource-model-source-configuration)), you should specify
the Provider Name for the parser as the format for the source:

    resources.source.1.format=myformat

This would specify the use of "myformat" provider.

In other cases, the exact name of the provider may not be known (for example 
when loading content from a remote URL).  Each Generator and Parser must define
a list of MIME Type strings and file extensions that they support. These 
are used to determine which parser/generator is to be used.

## When Node Execution Service providers are invoked

RunDeck executes Command items on Nodes.  The command may be part of a Workflow as defined
in a Job, and it may be executed multiple times on different nodes.

Currently three "kinds" of Command items can be specified in Workflows:

1. "exec" commands - simple system command strings
2. "script" commands - either embedded script content, or server-local script 
files can be sent to the specified node and then executed with a set of input arguments.
3. "jobref" commands - references to other Jobs by name that will be executed with
a set of input arguments.

RunDeck uses the NodeExecutor and FileCopier services as part of the process of 
executing these command types.

The procedure for executing an "exec" command is:

1. load the NodeExecutor provider for the node and context
2. call the NodeExecutor#executeCommand method

The procedure for executing a "script" command is:

1. load the FileCopier provider for the node and context
2. call the FileCopier#copy* method 
3. load the NodeExecutor provider for the node and context
4. Possibly execute an intermediate command (such as "chmod +x" on the copied file)
5. execute the NodeExecutor#executeCommand method, passing the filepath of the 
  copied file, and any arguments to the script command.

## Built-in providers

RunDeck uses a few built-in providers to provide the default service:

### Node Execution services

For NodeExecutor, these providers:

`local`

:   local execution of a command 

`jsch-ssh`

:   remote execution of a command via SSH, requiring the "hostname", and "username" attributes on a node.

For FileCopier, these providers:

`local`

:   creates a local temp file for a script

`jsch-scp`

:   remote copy of a command via SCP, requiring the "hostname" and  "username" attributes on a node.

#### SSH Provider

The SSH Node Executor and File Copier are included as the default providers for RunDeck.

Out of the box typical node configuration to make use of these is simple. 

* Set the `hostname` attribute for the nodes.  It can be in the format "hostname:port" to indicate that a non-default port should be used. The default port is 22.
* Set the `username` attribute for the nodes to the username to connect to the remote node.
* set up public/private key authentication from the RunDeck server to the nodes

This will allow remote command and script execution on the nodes.

See below for more configuration options.

##### Configuring SCP File Copier

In addition to the general SSH configuration mentioned for in this section, some additional configuration can be done for SCP. 

When a Script is executed on a remote node, it is copied over via SCP first, and then executed.  In addition to the SSH connection properties, these node attributes
can be configured for SCP:

* `file-copy-destination-dir`: The directory on the remote node to copy the script file to before executing it. The default value is `C:/WINDOWS/TEMP/` on Windows nodes, and `/tmp` for other nodes.
* `osFamily`: specify "windows" for windows nodes.

##### Configuring SSH Authentication type

SSH authentication can be done in two ways, via password or public/private key.

By default, public/private key is used, but this can be changed on a node, project, or framework scope.

The mechanism used is determined by the `ssh-authentication` property.  This property can have two different values:

* `password`
* `privateKey` (default)

When connecting to a particular Node, this sequence is used to determine the correct authentication mechanism:

1. **Node level**: `ssh-authentication` attribute on the Node. Applies only to the target node.
2. **Project level**: `project.ssh-authentication` property in `project.properties`.  Applies to any project node by default.
3. **RunDeck level**: `framework.ssh-authentication` property in `framework.properties`. Applies to all projects by default.

If none of those values are set, then the default public/private key authentication is used.

##### Configuring SSH Username

The username used to connect via SSH is taken from the `username` Node attribute:

* `username="user1"`

This value can also include a property reference if you want to dynamically change it, for example to the name of the current RunDeck user, or the username submitted as a Job Option value:

* `${job.username}` - uses the username of the user executing the RunDeck execution.
* `${option.someUsername}` - uses the value of a job option named "someUsername".

If the `username` node attribute is not set, then the static value provided via project or framework configuration is used. The username for a node is determined by looking for a value in this order:

1. **Node level**: `username` node attribute. Can contain property references to dynamically set it from Option or Execution values.
2. **Project level**: `project.ssh.user` property in `project.properties` file for the project.
3. **RunDeck level**: `framework.ssh.user` property in `framework.properties` file for the RunDeck installation.

##### Configuring SSH private keys

The default authentication mechanism is public/private key.

The built-in SSH connector allows the private key to be specified in several different ways.  You can configure it per-node, per-project, or per-RunDeck instance.

When connecting to the remote node, RunDeck will look for a property/attribute specifying the location of the private key file, in this order, with the first match having precedence:

1. **Node level**: `ssh-keypath` attribute on the Node. Applies only to the target node.
2. **Project level**: `project.ssh-keypath` property in `project.properties`.  Applies to any project node by default.
3. **RunDeck level**: `framework.ssh-keypath` property in `framework.properties`. Applies to all projects by default.
4. **RunDeck level**:  `framework.ssh.keypath` property in `framework.properties`. Applies to all projects by default (included for compatibility with Rundeck < 1.3). (default value: `~/.ssh/id_rsa`).

##### Configuring SSH Password Authentication

Password authentication works in the following way:

* A Job must be defined specifying a Secure Option to prompt the user for the password
* Target nodes must be configured for password authentication
* When the user executes the Job, they are prompted for the password.  The Secure Option value for the password is not stored in the database, and is used only for that execution.

Therefore Password authentication has several requirements and some limitations:

1. Password-authenticated nodes can only be executed on via a defined Job, not via Ad-hoc commands (yet).
2. Each Job that will execute on password-authenticated Nodes must define a Secure Option to prompt the user for the password before execution.
3. All Nodes using password authentication for a Job must have an equivalent Secure Option defined, or may use the same option name (or the default) if they share authentication passwords.

Passwords for the nodes are input either via the GUI or arguments to the job if executed via CLI or API.

To enable SSH Password authentication, first make sure the `ssh-authentication` value is set as described in [Configuring SSH Authentication type](#configuring-ssh-authentication-type).

Next, configure a Job, and include an Option definition where `secureInput` is set to `true`.  The name of this option can be anything you want, but the default value of `sshPassword` assumed by the node configuration is easiest.

If the value is not `sshPassword`, then make sure to set the following attribute on each Node for password authentication:

* `ssh-password-option` = "`option.NAME`" where NAME is the name of the Job's secure option.

An example Node and Job option configuration are below:

    <node name="egon" description="egon" osFamily="unix"
        username="rundeck"
        hostname="egon"
        ssh-authentication="password"
        ssh-password-option="option.<PASSWORD>" />

Job:

    <joblist>
        <job>
            ...
            <context>
              <project>project</project>
              <options>
                <option required='true' name='sshPassword1' secure='true' />
              </options>
            </context>
            ...
        </job>
    </joblist>


### Resource Model Sources
<commit_msg>Add sudo password auth docs [#482]<commit_after>
RunDeck Plugins
===========

Plugins for RunDeck contain new Providers for some of the Services used by
the RunDeck core.

RunDeck comes with some built-in providers for these services, but Plugins
let you write your own, or use third-party implementations.

RunDeck currently comes installed with a few useful plugins: script-plugin and 
stub-plugin.  See [Pre-installed plugins](#pre-installed-plugins) for more info.

## Installing Plugins

Installation of plugins is simple:

Put the plugin file, such as `plugin.jar` or `some-plugin.zip`, into the RunDeck 
server's libext dir:

    cp some-plugin.zip $RDECK_BASE/libext

The plugin is now enabled, and any providers it defines can be used by nodes
or projects.

The RunDeck server does not have to be restarted.

## Uninstalling or Updating Plugins

You can simply remove the plugin files from `$RDECK_BASE/libext` to uninstall
them.

You can overwrite an old plugin with a newer version to update it.

## About Plugins

Plugins are files that contain one or more Service Provider implementations. Each
plugin file could contain multiple Providers for different types of services,
however typically each plugin file would contain only providers related in some
fashion.

RunDeck includes a number of "built-in" providers, as well as a few 
"included" plugin files.

In this document "plugin" and "provider" are used somewhat interchangably. When 
referring to an actual file containing the provider implementations we will say
"plugin file".

![RunDeck Providers and Plugin Files](figures/fig1102.png)

## Types of Plugins

RunDeck supports several different types of plugins to perform different kinds 
of services.

### Node Execution Plugins

These plugins define ways of executing commands on nodes, and copying files to nodes.  

More information:

* Configuration: [Node Execution Services](#node-execution-services)
* Lifecycle: [When Node Execution Service providers are invoked](#when-node-execution-service-providers-are-invoked)
* Built-in Providers: [Node Execution services](#node-execution-services-1)
* Included Plugins: [Pre-installed plugins](#pre-installed-plugins)

### Resource Model Source Plugins

These plugins define mechanisms for retrieving Resource Model information from a
specific kind of source (such as a URL, file, or set of files in a directory).

More information:

* Configuration: [Resource Model Sources](#resource-model-sources)
* Built-in Providers: [Resource Model Sources](#resource-model-sources-1)

### Resource Format Plugins

These plugins define parsers and generators for different document formats, and
are used by the Resource Model Source Plugins, as well as other parts of the
RunDeck system.

More information:

* Configuration: [Resource Format Generators and Parsers](#resource-format-generators-and-parsers)
* Built-in Providers: [Resource Format services](#resource-format-services)

## About Services and Providers

The RunDeck core makes use of several different "Services" that provide
functionality for the different steps necessary to execute workflows, jobs, 
and commands across multiple nodes.

Each Service makes use of "Providers". Each Provider has a unique "Provider Name"
that is used to identify it, and most Services have default Providers unless
you specify different ones to use.

![RunDeck Services and Providers](figures/fig1101.png)

Services fall into different categories, which determine how and where they are used.

*Service Categories*:

1. **Node Execution services** - providers of these services operate in the context of a single Node definition, and
  can be configured at Node scope or higher:

    1. Node Executor - these providers define ways of executing a command on a Node (local or remote)
    2. File Copier - these providers define ways of copying files to a Node.

2. **Project services**

    1. Resource Model Source - (aka "Resource Providers") these define ways of retrieving Node resources for a Project 

3. **Global services** (framework level)

    1. Resource Format Parser - these define document format parsers
    2. Resource Format Generators - these define document format generators

Specifics of how providers of these plugins work is listed below.

RunDeck Plugins can contain more than one Provider.

## Using Providers

### Node Execution Services

The two *Node services*, Node Executor and File Copier, are both configured similarly.
They are configured for particular nodes on a node-specific basis,
or set as a default provider for a project or for the system.

If multiple providers are defined the most specific definition takes precedence
in this order:

1. Node specific
2. Project scope
3. Framework scope

#### Node Specific

To enable a provider for a node, add an attribute to the node definition.

*Node Executor provider attributes*:

`node-executor`

:    specifies the provider name for a non-local node.

`local-node-executor`

:    specifies the provider name for the local (server) node.


*FileCopier provider attributes*:

`file-copier`

:    specifies the provider by name for a non-local node.

`local-file-copier`

:    specifies the provider by name for the local (server) node.

Example Node in YAML specifying `stub` NodeExecutor and FileCopier:

    remotehost:
        hostname: remotehost
        node-executor: stub
        file-copier: stub

#### Project or Framework Scope

*Node Executor*

You can define the default connection providers to use for nodes at either the Project or
Framework scope (or both).  To do so, configure any of the following properties
in the `project.properties` or the `framework.properties` files.  

`service.NodeExecutor.default.provider`

:   Specifies the default NodeExecutor provider for remote nodes

`service.NodeExecutor.default.local.provider`

:   Specifies the default Node Executor provider for the  local node.

*File Copier*

`service.FileCopier.default.provider`

:   Specifies the default File Copier provider for remote nodes.

`service.FileCopier.default.local.provider`

:   Specifies the default File Copier provider for the local node.

Example `project.properties` to set default local providers to `stub`:

    service.NodeExecutor.default.local.provider=stub
    service.FileCopier.default.local.provider=stub

### Resource Model Sources

The *Resource Model Sources* providers can be configured for a single project 
in the `project.properties` file.

You can define multiple Resource Model Sources for the project, and can mix and match
the specific providers depending on your needs.

When you define multiple Source providers in a project, then the resulting set of Nodes will 
effectively be a merge of all the sources, in the order in which they are declared. This
means that if two or more Sources provide a definition of a node with the same name, then
the definition from lowest Source in the list will be used.

The order that the providers are loaded (and thus the nodes are merged) is:

1. `project.resources.file`: A File Model Source with default configuration.
2. `project.resources.url`: A URL Model Source with default configuration. (optional)
3. All `resources.source.N` configurations in order starting at 1

#### Resource Model Source configuration

The `project.properties` file for each project allows you to configure the Resource Model Sources in these ways:

* Define `project.resources.file` - this file path is used as a File Source path, with *autogeneration* and *includeServerNode* both true.
* Define `project.resources.url` - this URL is used as a URL Source url, with caching enabled

You may also define a list of more sources in this way:

Starting at index `1`, define these properties for your Source numbered `N`:

    resources.source.N.type=<provider-name>
    resources.source.N.config.<property>=<value>
    resources.source.N.config.<property2>=<value2>
    ...

Using one of the available Resource Model Source provider names for the `<provider-name>` value. For each Resource Model Source provider, 
you can specify the configuration properties for the source.

Example project.properties configuration of a default File provider, and two other providers:

    project.resources.file=/home/rundeck/projects/example/etc/resources.xml
    
    resources.source.1.type=url
    resources.source.1.url=http://server/nodes.yaml
    
    resources.source.2.type=directory
    resources.source.2.directory=/home/rundeck/projects/example/resources

### Resource Format Generators and Parsers

Resource Format Generators and Parsers define support for file formats that can
be generated from or parsed into a set of Resource Node definitions.

These are used by other parts of the system, such as the Resource Model Sources.

There is no configuration necessary to use these providers, however the specific
Provider Name that each generator and parser defines has to be known in order
to make use of the provider.  The specific Provider Name is used as the 
"format name" when you want to use the parser or generator.

For example, to enable a particular Resource Format parser to be used by a File
Resource Model Source (see [File Resource Model Source Configuration](#file-resource-model-source-configuration)), you should specify
the Provider Name for the parser as the format for the source:

    resources.source.1.format=myformat

This would specify the use of "myformat" provider.

In other cases, the exact name of the provider may not be known (for example 
when loading content from a remote URL).  Each Generator and Parser must define
a list of MIME Type strings and file extensions that they support. These 
are used to determine which parser/generator is to be used.

## When Node Execution Service providers are invoked

RunDeck executes Command items on Nodes.  The command may be part of a Workflow as defined
in a Job, and it may be executed multiple times on different nodes.

Currently three "kinds" of Command items can be specified in Workflows:

1. "exec" commands - simple system command strings
2. "script" commands - either embedded script content, or server-local script 
files can be sent to the specified node and then executed with a set of input arguments.
3. "jobref" commands - references to other Jobs by name that will be executed with
a set of input arguments.

RunDeck uses the NodeExecutor and FileCopier services as part of the process of 
executing these command types.

The procedure for executing an "exec" command is:

1. load the NodeExecutor provider for the node and context
2. call the NodeExecutor#executeCommand method

The procedure for executing a "script" command is:

1. load the FileCopier provider for the node and context
2. call the FileCopier#copy* method 
3. load the NodeExecutor provider for the node and context
4. Possibly execute an intermediate command (such as "chmod +x" on the copied file)
5. execute the NodeExecutor#executeCommand method, passing the filepath of the 
  copied file, and any arguments to the script command.

## Built-in providers

RunDeck uses a few built-in providers to provide the default service:

### Node Execution services

For NodeExecutor, these providers:

`local`

:   local execution of a command 

`jsch-ssh`

:   remote execution of a command via SSH, requiring the "hostname", and "username" attributes on a node.

For FileCopier, these providers:

`local`

:   creates a local temp file for a script

`jsch-scp`

:   remote copy of a command via SCP, requiring the "hostname" and  "username" attributes on a node.

#### SSH Provider

The SSH Node Executor and File Copier are included as the default providers for RunDeck.

Out of the box typical node configuration to make use of these is simple. 

* Set the `hostname` attribute for the nodes.  It can be in the format "hostname:port" to indicate that a non-default port should be used. The default port is 22.
* Set the `username` attribute for the nodes to the username to connect to the remote node.
* set up public/private key authentication from the RunDeck server to the nodes

This will allow remote command and script execution on the nodes.

See below for more configuration options.

**Sudo Password Authentication**

The SSH Provider also includes support for a secondary Sudo Password Authentication. This simulates a user writing a password to the terminal into a password prompt when invoking a "sudo" command that requires password authentication.

##### Configuring SCP File Copier

In addition to the general SSH configuration mentioned for in this section, some additional configuration can be done for SCP. 

When a Script is executed on a remote node, it is copied over via SCP first, and then executed.  In addition to the SSH connection properties, these node attributes
can be configured for SCP:

* `file-copy-destination-dir`: The directory on the remote node to copy the script file to before executing it. The default value is `C:/WINDOWS/TEMP/` on Windows nodes, and `/tmp` for other nodes.
* `osFamily`: specify "windows" for windows nodes.

##### Configuring SSH Authentication type

SSH authentication can be done in two ways, via password or public/private key.

By default, public/private key is used, but this can be changed on a node, project, or framework scope.

The mechanism used is determined by the `ssh-authentication` property.  This property can have two different values:

* `password`
* `privateKey` (default)

When connecting to a particular Node, this sequence is used to determine the correct authentication mechanism:

1. **Node level**: `ssh-authentication` attribute on the Node. Applies only to the target node.
2. **Project level**: `project.ssh-authentication` property in `project.properties`.  Applies to any project node by default.
3. **RunDeck level**: `framework.ssh-authentication` property in `framework.properties`. Applies to all projects by default.

If none of those values are set, then the default public/private key authentication is used.

##### Configuring SSH Username

The username used to connect via SSH is taken from the `username` Node attribute:

* `username="user1"`

This value can also include a property reference if you want to dynamically change it, for example to the name of the current RunDeck user, or the username submitted as a Job Option value:

* `${job.username}` - uses the username of the user executing the RunDeck execution.
* `${option.someUsername}` - uses the value of a job option named "someUsername".

If the `username` node attribute is not set, then the static value provided via project or framework configuration is used. The username for a node is determined by looking for a value in this order:

1. **Node level**: `username` node attribute. Can contain property references to dynamically set it from Option or Execution values.
2. **Project level**: `project.ssh.user` property in `project.properties` file for the project.
3. **RunDeck level**: `framework.ssh.user` property in `framework.properties` file for the RunDeck installation.

##### Configuring SSH private keys

The default authentication mechanism is public/private key.

The built-in SSH connector allows the private key to be specified in several different ways.  You can configure it per-node, per-project, or per-RunDeck instance.

When connecting to the remote node, RunDeck will look for a property/attribute specifying the location of the private key file, in this order, with the first match having precedence:

1. **Node level**: `ssh-keypath` attribute on the Node. Applies only to the target node.
2. **Project level**: `project.ssh-keypath` property in `project.properties`.  Applies to any project node by default.
3. **RunDeck level**: `framework.ssh-keypath` property in `framework.properties`. Applies to all projects by default.
4. **RunDeck level**:  `framework.ssh.keypath` property in `framework.properties`. Applies to all projects by default (included for compatibility with Rundeck < 1.3). (default value: `~/.ssh/id_rsa`).

##### Configuring SSH Password Authentication

Password authentication works in the following way:

* A Job must be defined specifying a Secure Option to prompt the user for the password
* Target nodes must be configured for password authentication
* When the user executes the Job, they are prompted for the password.  The Secure Option value for the password is not stored in the database, and is used only for that execution.

Therefore Password authentication has several requirements and some limitations:

1. Password-authenticated nodes can only be executed on via a defined Job, not via Ad-hoc commands (yet).
2. Each Job that will execute on password-authenticated Nodes must define a Secure Option to prompt the user for the password before execution.
3. All Nodes using password authentication for a Job must have an equivalent Secure Option defined, or may use the same option name (or the default) if they share authentication passwords.

Passwords for the nodes are input either via the GUI or arguments to the job if executed via CLI or API.

To enable SSH Password authentication, first make sure the `ssh-authentication` value is set as described in [Configuring SSH Authentication type](#configuring-ssh-authentication-type).

Next, configure a Job, and include an Option definition where `secureInput` is set to `true`.  The name of this option can be anything you want, but the default value of `sshPassword` assumed by the node configuration is easiest.

If the value is not `sshPassword`, then make sure to set the following attribute on each Node for password authentication:

* `ssh-password-option` = "`option.NAME`" where NAME is the name of the Job's secure option.

An example Node and Job option configuration are below:

    <node name="egon" description="egon" osFamily="unix"
        username="rundeck"
        hostname="egon"
        ssh-authentication="password"
        ssh-password-option="<PASSWORD>" />

Job:

    <joblist>
        <job>
            ...
            <context>
              <project>project</project>
              <options>
                <option required='true' name='sshPassword1' secure='true' />
              </options>
            </context>
            ...
        </job>
    </joblist>


##### Configuring Secondary Sudo Password Authentication

The SSH provider supports a secondary authentication mechanism: Sudo password authentication.  This is useful if your security requirements are such that you require the SSH connection to be under a specific user's account instead of a generic "rundeck" account, and you still need to allow "sudo" level commands to be executed requiring a password to be entered.

This works in the following way:

* On Job execution, the user is prompted to enter a Sudo password
* After connecting to the remote node via SSH, a command requiring "sudo" authentication is issued, such as "sudo -u otheruser /sbin/some-command"
* The remote node will prompt for a sudo password, expecting user input
* The SSH Provider will write the password to the remote node
* The sudo command will execute as if a user had entered the command

Similarly to SSH Password authentication, Sudo Password Authentication requires:

* A Job must be defined specifying a Secure Option to prompt the user for the password
* Target nodes must be configured for Sudo authentication
* When the user executes the Job, they are prompted for the password.  The Secure Option value for the password is not stored in the database, and is used only for that execution.

Therefore Sudo Password Authentication has several requirements and some limitations:

1. Sudo Password authenticated nodes can only be executed on via a defined Job, not via Ad-hoc commands (yet).
2. Each Job that will execute on Sudo Password Authenticated Nodes must define a Secure Option to prompt the user for the Sudo password before execution.
3. All Nodes using Sudo password authentication for a Job must have an equivalent Secure Option defined, or may use the same option name (or the default) if they share sudo authentication passwords.

Passwords for the nodes are input either via the GUI or arguments to the job if executed via CLI or API.

To enable Sudo Password Authentication, set the `sudo-command-enabled` to `true` for each node.

* `sudo-command-enabled` - set to "true" to enable Sudo Password Authentication: *required*.

 You can also configure these attributes, which also have equivalent properties to set at the Project and RunDeck scopes. Simply set the `project.NAME` in project.properties, or `framework.NAME` in framework.properties:
 
* `sudo-command-pattern` - a regular expression to detect when a command execution should expect to require Sudo authentication. Default pattern is `^sudo$`.
* `sudo-password-option` - an option reference ("option.NAME") to define which secure option value to use as password.  The default is `option.sudoPassword`.
* `sudo-prompt-pattern` - a regular expression to detect the password prompt for the Sudo authentication. The default pattern is `^\[sudo\] password for .+: .*`
* `sudo-failure-pattern` - a regular expression to detect the password failure response.  The default pattern is `^.*try again.*`.
* `sudo-prompt-max-lines` - maximum lines to read when expecting the password prompt. (default: `12`).
* `sudo-prompt-max-timeout` - maximum milliseconds to wait for input when expecting the password prompt. (default `5000`)
* `sudo-response-max-lines` - maximum lines to read when looking for failure response. (default: `1`).
* `sudo-response-max-timeout` - maximum milliseconds to wait for response when detecting the failure response. (default `5000`)
* `sudo-fail-on-prompt-max-lines` - true/false. If true, fail execution if max lines are reached looking for password prompt. (default: `false`)
* `sudo-success-on-prompt-threshold` - true/false. If true, succeed (without writing password), if the input max lines are reached without detecting password prompt. (default: `true`).
* `sudo-fail-on-prompt-timeout` - true/false. If true, fail execution if timeout reached looking for password prompt. (default: `true`)
* `sudo-fail-on-response-timeout` - true/false. If true, fail on timeout looking for failure message. (default: `false`)

Note: the default values have been set for the unix "sudo" command, but can be overridden if you need to customize the interaction.

Next, configure a Job, and include an Option definition where `secureInput` is set to `true`.  The name of this option can be anything you want, but the default value of `sudoPassword` recognized by the plugin can be used.

If the value is not `sudoPassword`, then make sure to set the following attribute on each Node for password authentication:

* `sudo-password-option` = "`option.NAME`" where NAME is the name of the Job's secure option.

An example Node and Job option configuration are below:

    <node name="egon" description="egon" osFamily="unix"
        username="rundeck"
        hostname="egon"
        sudo-command-enabled="true"
        sudo-password-option="<PASSWORD>" />

Job:

    <joblist>
        <job>
             <sequence keepgoing='false' strategy='node-first'>
              <command>
                <exec>sudo apachectl restart</exec>
              </command>
            </sequence>

            <context>
              <project>project</project>
              <options>
                <option required='true' name='sudoPassword2' secure='true' description="Sudo authentication password"/>
              </options>
            </context>
            ...
        </job>
    </joblist>


### Resource Model Sources

{'fraction_non_alphanumeric': 0.06390075346738974, 'fraction_numerical': 0.0034074002975476316, 'mean_word_length': 4.191852497819858, 'pattern_counts': {'":': 0, '<': 62, '<?xml version=': 0, '>': 60, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6181831', 'n_tokens_mistral': 10668, 'n_tokens_neox': 10215, 'n_words': 5607}