Adding Custom Hosts – Rancher

Add custom hosts

If you already have Linux machines deployed and just want to add them to Rancher, click the Custom icon. In the user interface, you will be provided with a docker command to run on any host. The docker command starts the rancher/agent container on the host.

If you use different environments, the command provided through the user interface will be unique to any environment you are in.

Make sure that you are in the environment to which you want to add hosts. The environment is displayed in the upper-left corner. When you first log in to your Rancher instance, you are in the default environment.

Once your hosts are added to Rancher, they are available to add services.

Note: Make sure that the timestamp of your host on your server and hosts is the same and that you have access to the containers on the host. For more information, see Rancher accesses the shell/records of a container.



With each host, you have the ability to add tags to help you organize your hosts. Tags are added as an environment variable when you start the farmer/agent container. The host label in the UI will be a key/value pair and the keys must be unique identifiers. If you added two keys with different values, we will take the last value entered to use as a key/value pair.

When adding tags to hosts, you can use these tags when scheduling services/load balancers and creating a whitelist or blacklist of hosts for your services to run.

When adding a custom host, you can add the tags using the UI and it will automatically add the environment variable (CATTLE_HOST_LABELS) with the key/value pair in the UI screen command.


of security groups



For any hosts that are added, make sure that the security groups or firewalls allow traffic. If these are not enabled, Rancher functionality will be limited.

If you use the IPsec network controller, to and from all other hosts on UDP ports

    500 and 4500 If you

  • use the VXLAN network controller, to and from all other hosts on UDP ports 4789 Add hosts to

the same machine as the Rancher Server

If you are adding an agent host on the same machine as the Rancher server, You must edit the command provided from the user interface. In the user interface, you can specify the IP address that you want the Rancher agent container to use to manage the Rancher server. Automatically adds an environment variable to the command.

If you have added a host to the same host as the Rancher server, note that you will not be able to create any containers on the host that bind to port 8080. Since the Rancher server user interface is based on port 8080, there will be a port conflict and Rancher will stop working. If you need to use port 8080 for your containers, you can start the Rancher server using a different port.

Hosts behind

a proxy To configure

an HTTP proxy, configure the docker daemon to point to the proxy. Before adding the custom host, edit the /etc/default/docker file to point to the proxy and restart docker.

Within the file, edit the #export http_proxy=”” to point to your proxy. Save your changes, and then restart Docker. Restarting Docker is different on each operating system.

Note: If you run Docker with systemd, follow the Docker instructions on how to configure HTTP proxy.

You do not need to add additional environment variables to the command to start Rancher agents. You just need to make sure your Docker daemon is set up correctly.

Virtual machines

with private and public IP addresses

By default, the IP of a virtual machine with a private IP and a public IP will be set to match the IP specified in the registration URL. For example, if a private IP is used in the registration URL, the host’s private IP will be used. If you want to change the IP address of the host, you will need to edit the command provided from the user interface. For the Rancher agent container to start successfully, set the CATTLE_AGENT_IP environment variable to the desired IP address. All hosts within Rancher must be on the same network as the Rancher server.

If you need to correct the host IP after the agent has connected, run the custom command again.

Note: When configuring the private IP address, existing containers in Rancher will not be part of the same managed network.

Contact US