Free trial

Automating Tentacle installation

The Tentacle agent can be automatically installed from the command line. This is very useful if you’re deploying to a large number of servers, or you’re provisioning servers automatically.

Cloning Tentacle VMs In a virtualized environment, it may be desirable to install Tentacle on a base virtual machine image, and clone this image to create multiple machines.

If you choose to do this, please do not complete the configuration wizard before taking the snapshot. The configuration wizard generates a unique per-machine cryptographic certificate that should not be duplicated. Instead, use PowerShell to automate configuration after the clone has been materialized.

Tentacle installers

Tentacle comes in an MSI that can be deployed via group policy or other means.

Download the Tentacle MSI

The latest Tentacle MSI can always be downloaded from the Octopus Deploy downloads page.

Permalinks to always get the latest MSIs are:

To install the MSI silently run the following command:

msiexec /i Octopus.Tentacle.<version>.msi /quiet

By default, the Tentacle files are installed under %programfiles(x86)%. You can change the installation directory, with the following command:

msiexec INSTALLLOCATION=C:\YourDirectory /i Octopus.Tentacle.<version>.msi /quiet

While you can set a custom INSTALLLOCATION for the Tentacle, please be aware that upgrades initiated by Octopus Server will install the upgraded Tentacle in the default location. This may have an impact if you are using the Service Watchdog.

Configuration

The MSI installer simply extracts files and adds some shortcuts and event log sources. The actual configuration of Tentacle is done later, and this can be automated too.

To configure the Tentacle in listening or polling mode, it’s easiest to run the installation wizard once, and at the end, use the Show Script option in the setup wizard. This will show you the command-line equivalent to configure a Tentacle.

Advanced configuration options

When configuring your Tentacle, you can configure advanced options, such as proxies, machine policies, and tenants, which can also be automated. Use the setup wizard to configure the Tentacle, and click the Show Script link which will show you the command-line equivalent to configure the Tentacle.

Example: Listening Tentacle

The following example configures a listening Tentacle, and registers it with an Octopus Server:

Using Tentacle.exe to create Listening Tentacle instance

cd "C:\Program Files\Octopus Deploy\Tentacle"

Tentacle.exe create-instance --instance "Tentacle" --config "C:\Octopus\Tentacle.config" --console
Tentacle.exe new-certificate --instance "Tentacle" --if-blank --console
Tentacle.exe configure --instance "Tentacle" --reset-trust --console
Tentacle.exe configure --instance "Tentacle" --home "C:\Octopus" --app "C:\Octopus\Applications" --port "10933" --console
Tentacle.exe configure --instance "Tentacle" --trust "YOUR_OCTOPUS_THUMBPRINT" --console
"netsh" advfirewall firewall add rule "name=Octopus Deploy Tentacle" dir=in action=allow protocol=TCP localport=10933
Tentacle.exe register-with --instance "Tentacle" --server "http://YOUR_OCTOPUS" --apiKey="API-YOUR_API_KEY" --role "web-server" --environment "Staging" --comms-style TentaclePassive --console
Tentacle.exe service --instance "Tentacle" --install --start --console

You can also register a Tentacle with the Octopus Server after it has been installed by using Octopus.Client (i.e. register-with could be omitted above and the following could be used after the instance has started. See below for how to obtain the Tentacle’s thumbprint):

Using Octopus.Client to register a Tentacle in an Octopus Server

Add-Type -Path 'Newtonsoft.Json.dll'
Add-Type -Path 'Octopus.Client.dll'

$octopusApiKey = 'API-ABCXYZ'
$octopusURI = 'http://YOUR_OCTOPUS'

$endpoint = new-object Octopus.Client.OctopusServerEndpoint $octopusURI, $octopusApiKey
$repository = new-object Octopus.Client.OctopusRepository $endpoint

$tentacle = New-Object Octopus.Client.Model.MachineResource

$tentacle.name = "Tentacle registered from client"
$tentacle.EnvironmentIds.Add("Environments-1")
$tentacle.Roles.Add("WebServer")

$tentacleEndpoint = New-Object Octopus.Client.Model.Endpoints.ListeningTentacleEndpointResource
$tentacle.EndPoint = $tentacleEndpoint
$tentacle.Endpoint.Uri = "https://YOUR_TENTACLE:10933"
$tentacle.Endpoint.Thumbprint = "YOUR_TENTACLE_THUMBPRINT"

$repository.machines.create($tentacle)

Want to register your Tentacles another way? Take a look at our examples for ways to register Tentacles using the Octopus REST API.

Example: Polling Tentacle

The following example configures a Polling Tentacle, and registers it with an Octopus Server:

Polling Tentacle

cd "C:\Program Files\Octopus Deploy\Tentacle"

Tentacle.exe create-instance --instance "Tentacle" --config "C:\Octopus\Tentacle.config" --console
Tentacle.exe new-certificate --instance "Tentacle" --if-blank --console
Tentacle.exe configure --instance "Tentacle" --reset-trust --console
Tentacle.exe configure --instance "Tentacle" --home "C:\Octopus" --app "C:\Octopus\Applications" --noListen "True" --console
Tentacle.exe register-with --instance "Tentacle" --server "http://YOUR_OCTOPUS" --name "YOUR_TENTACLE_NAME" --apiKey "API-YOUR_API_KEY" --comms-style "TentacleActive" --server-comms-port "10943" --force --environment "YOUR_TENTACLE_ENVIRONMENTS" --role "YOUR_TENTACLE_ROLES" --console
Tentacle.exe service --instance "Tentacle" --install --start --console

Tips:

  • If you are running this from a PowerShell remote session, make sure to add --console at the end of each command to force Tentacle.exe not to run as a service.
  • Want to register your Tentacles another way? Take a look at our examples for ways to register Tentacles using the Octopus REST API.

Obtaining the Tentacle thumbprint

If you don’t know the thumbprint for the above PowerShell scripts, it can be obtained with the following command line option:

Tentacle.exe show-thumbprint --instance "Tentacle" --nologo

Export and import Tentacle certificates without a profile

When the Tentacle agent is configured, the default behavior is to generate a new X.509 certificate. When automating the provisioning of Tentacles on a machine, however, you may run into problems when trying to generate a certificate when running as a user without a profile loaded.

A simple workaround is to generate a certificate on one machine (such as your workstation), export it to a file, and then import that certificate when provisioning Tentacles.

Generating and exporting a certificate

Install the Tentacle agent on a computer, and run the following command:

tentacle.exe new-certificate -e MyFile.txt

The output file will now contain a base-64 encoded version of a PKCS#12 export of the X.509 certificate and corresponding private key. This file is now ready to be used in your setup scripts.

Importing a certificate

When automatically provisioning your Tentacle, the commands typically look something like this:

Tentacle.exe create-instance --instance "Tentacle" --config "C:\Octopus\Tentacle\Tentacle.config" --console
Tentacle.exe new-certificate --instance "Tentacle" --console
Tentacle.exe configure --instance "Tentacle" --home "C:\Octopus" --console
...

Replace the new-certificate command with import-certificate. For example:

Tentacle.exe create-instance --instance "Tentacle" --config "C:\Octopus\Tentacle\Tentacle.config" --console
Tentacle.exe import-certificate --instance "Tentacle" -f MyFile.txt --console
Tentacle.exe configure --instance "Tentacle" --home "C:\Octopus" --console
...

Desired State Configuration

Tentacles can also be installed via Desired State Configuration (DSC). Using the module from the OctopusDSC GitHub repository, you can add, remove, start and stop Tentacles in either Polling or Listening mode.

The following PowerShell script will install a Tentacle listening on port 10933 against the Octopus Server at https://YOUR_OCTOPUS, add it to the Development environment and assign the web-server and app-server roles:

DSC Configuration

Configuration SampleConfig
{
    param ($ApiKey, $OctopusServerUrl, $Environments, $Roles, $ListenPort)

    Import-DscResource -Module OctopusDSC

    Node "localhost"
    {
        cTentacleAgent OctopusTentacle
        {
            Ensure = "Present"
            State = "Started"

            # Tentacle instance name. Leave it as 'Tentacle' unless you have more
            # than one instance
            Name = "Tentacle"

            # Registration - all parameters required
            ApiKey = $ApiKey
            OctopusServerUrl = $OctopusServerUrl
            Environments = $Environments
            Roles = $Roles

            # Optional settings
            ListenPort = $ListenPort
            DefaultApplicationDirectory = "C:\Applications"
        }
    }
}

# Execute the configuration above to create a mof file
SampleConfig -ApiKey "API-YOUR_API_KEY" -OctopusServerUrl "https://YOUR_OCTOPUS/" -Environments @("Development") -Roles @("web-server", "app-server") -ListenPort 10933

# Run the configuration
Start-DscConfiguration .\SampleConfig -Verbose -wait

# Test the configuration ran successfully
Test-DscConfiguration

Settings and properties

To review the latest available settings and properties, refer to the OctopusDSC Tentacle readme.md in the GitHub repository.

DSC can be applied in various ways, such as Group Policy, a DSC Pull Server, Azure Automation, or even via configuration management tools such as Chef or Puppet. A good resource to learn more about DSC is the Channel 9 Getting Started with DSC series.

For an in depth look, check out the sample walk-through of how to use DSC with an Azure ARM template to deploy and configure the Tentacle on an Azure VM.

Rootless Instance Creation

Creating a named instance with the --instance parameter as shown in the examples above will register the instance details in a central registry to allow it to be easily managed via its unique name. Access to this central registry on the target machine is under C:\ProgramData\Octopus on Windows and /etc/octopus on other Platforms. For some high-security low-trust environments, access to these locations may not be possible, so Octopus supports creating Tentacle instances that isolate all their configuration in a single directory.

Omitting the --instance and --configuration parameters from the create-instance command will create the Tentacle.config configuration file in the current working directory of the executing process. As such, it will not require any elevated permissions to create. However, relevant OS permissions may still be necessary depending on the ports used. To manage this instance, all ensuing commands are required to be run either with the executable being invoked from the context of the initial configuration directory or with the --config parameter pointing to the configuration file that was created in that directory.

For example, running the following commands:

mkdir ~/mytentacle && cd ~/mytentacle
tentacle create-instance

will create a Tentacle configuration file in ~/mytentacle without needing access to the shared registry (typically stored on Linux at /etc/octopus). Subsequent commands to this instance can be performed by running the command directly from that location:

cd ~/mytentacle
tentacle configure --trust F9EFD9D31A04767AD73869F89408F587E12CB23C

Service Limitations

Due to the non-uniquely-named nature of these instances, only one such instance type can be registered as a service at any given time. An optional mechanism for running this instance is to use the agent command to start and run the Tentacle process inline. The delete-instance command will also have no effect, its purpose being largely to remove the instance details from the registry and preserving the configuration on disk.

Help us continuously improve

Please let us know if you have any feedback about this page.

Send feedback

Page updated on Sunday, January 1, 2023

Edit on GitHub