Install and configure a satellite server

This topic provides information on how to install and configure a satellite server.

Requirements for a satellite server

An Deploy satellite server must meet the following requirements:

• Operating system: Microsoft Windows (32-bit or 64-bit) or a Unix-based operating system running Java

• Java Runtime Environment: Java Development Kit (JDK) 11 (Oracle, IBM, or Apple)

• RAM: At least 2 GB of RAM available for the Deploy satellite module

• Hard disk space: Sufficient hard disk space to store the artifacts that will be deployed to this specific satellite server

• Version: Deploy and the satellite server must run the same version

Install the satellite

To install the Deploy satellite software:

1. Ensure that the satellite server meets the requirements.
2. Extract the satellite distribution ZIP file in the location on the server where you want to install the software.

tip

For information about installing Deploy Satellite as a service, see Install Deploy Satellite as a service.

Configure the satellite

Satellite servers communicate with Deploy through TCP connections. The satellite side of the connection is considered to be the server side. The satellite must open two ports and wait for Deploy to connect. One port is required for command handling, and the other is required for file (artifact) upload. Ensure that you configure satellite communication ports and that firewalls are opened for both incoming and outgoing traffic from Deploy to satellites and from satellites to Deploy.

note

If you change the satellite configuration, you must restart the satellite process. You do not have to restart Deploy.

Deploy Satellite does not require a restart after communication failure. The satellite.conf file is divided into two sections: for configuring the akka communication system and for configuring the akka task system. If a communication failure occurs between the satellite and the Deploy server, the akka task system continues to function and only the akka communication system will require a restart.

If you added configuration options in satellite.conf under the akka key and you upgrade to Deploy version 7.2.0 or later, the satellite will not start. The satellite log will show an error and you will have to move the configuration options to satellite.communication.akka or satellite.tasks.akka.

Note: Starting with Deploy version 23.1.6, if you use Deploy on a Kubernetes cluster, set the xl.satellite.streaming.connection-resolver property in conf/satellite.conf to blocking. This is to avoid port mismatches in NAT-enabled networks.

Configure the command handling channel

The satellite.hostname property in the SATELLITE_HOME/conf/satellite.conf file defines the command handling channel. If it is blank, the satellite will bind to the first host name that is resolved.

To override the property, modify this snippet:

satellite {
    hostname = <external IP / hostname>
}

You can then configure the port opened in the satellite.port property. The default value is 8380.

important

The satellite.hostname and satellite.port values must be identical to the values that you set when you add the satellite configuration item (CI) to Deploy. For more information, see Add a satellite server to Deploy.

Configure the file streaming port

In addition to command handling, a satellite requires a port to act as a streaming server for incoming files that are needed for a deployment. This port is automatically exchanged between Deploy and the satellite. You do not need to configure it manually. By default, port 8480 is opened on the satellite for file streaming.

The port is defined by the satellite.streaming.port property in SATELLITE_HOME/conf/satellite.conf:

satellite {
  streaming {
    port = <streaming port>
  }
}

Configure the upload timeout

You can configure a file upload idle timeout on a satellite server. The timeout corresponds to an idle TCP connection on the streaming server without an associated command. This will prevent unnecessary connections from being kept open on the satellite.

To configure the file upload idle timeout on a satellite server, change satellite.timeout.upload.idle in SATELLITE_HOME/conf/satellite.conf:

satellite {
  timeout {
    upload.idle = "<timeout>"
  }
}

You can specify the ping timeout in milliseconds, seconds, or minutes. For example: 100 ms or 10 seconds.

Configure the streaming chunk size

To ensure efficient file transfer without saturating the network, files are uploaded by chunk. You can adjust the chunk size to adapt it to the topology of your infrastructure.

To set the chunk size (in bytes) with satellite.streaming.chunk-size in SATELLITE_HOME/conf/satellite.conf:

satellite {
  streaming {
    chunk-size = <chunk size>
  }
}

Enable a streaming bandwidth limitation

To ensure efficient file transfer without saturating the network, limit the bandwidth that the streaming connection between Deploy and a satellite uses. The limit is defined per connection.

To enable this feature, change the following properties in SATELLITE_HOME/conf/satellite.conf:

satellite{
  streaming {
    throttle = on // off
    throttle-speed = 10000 // given in kB/sec. Must be at least 100kB/sec
  }
}

Configure file transfer location

To change the directory where Deploy transfers files to the satellite server, change the satellite.directory.workproperty in SATELLITE_HOME/conf/satellite.conf:

satellite {
    directory {
        work = "<your directory>"
    }
}

Files are stored in this directory by task.

Configure task recovery location

To change the directory where Deploy Satellite stores task recovery files, change the satellite.directory.recoveryproperty in SATELLITE_HOME/conf/satellite.conf:

satellite {
    directory {
        recovery = "<your directory>"
    }
}

Configure secure communication

Deploy communicates with satellite servers over a secure communication channel using TLS/SSL technology to encrypt data. For information about configuring SSL, see Configure secure communication between Deploy and satellites.

Configure the satellite to use Kerberos

If you are going to use Microsoft Windows domain accounts to access remote hosts with the WINRM_INTERNAL connection type, you must configure Kerberos on the satellite. For more information, see Set up Kerberos for WinRM.

Start the satellite

To start the satellite software, execute the appropriate script in the bin directory of the installation:

• Unix: run.sh
• Microsoft Windows: run.cmd