Skip to content

Servers

This guide will take you through everything related to the management of Servers in Keystash. The servers discussed here refer to any virtual machine, container or host that is running a Linux distribution with an SSH server.

Server List

  • The server list shows the status and details of all your servers that are connected to Keystash. Click "Server Management" and then "Servers" to view the list.

  • The following columns are shown in the list:

    • Hostname: The hostname as set on the server.
    • Status: This shows the status of the server within the last 5 minutes. The four different states are detailed here. You can hover over the status to get more details.
    • ID: This is a unique ID that represents the server. This ID is used in the configuration of the server, in the API and any any audit logs.
    • Location: This details the general geographic location that the external IP address is registered to based on the ASN as provided by the owner of the IP.
    • Provider: This details the provider or company that the external IP is registered to. This will typically be your cloud hosting provider such as AWS or DigitalOcean. However it can also be your ISP if the server is co-located at your offices or private data centre.
    • External IP: The external IP address as detected by Keystash when the server registered with our systems. Note that the IP could be NAT'd or proxied, in which case it would represent the IP address of the NAT gateway or proxy server. This in turn would affect the Location and Provider fields as discussed above.
    • Server Group: This is the Server Group in Keystash that the server has been assigned to during registration. You can always move a server to another Server Group by editing the server.
    • Created: The initial date and time the server was registered.
    • Actions: Any available actions that can be run against the server.

    Screenshot

Add Servers

Servers are added to Keystash by deploying the agent software on the server. Once the agent has been deployed the server will register with Keystash and automatically show up in the Server list.

  1. Click "Server Management" and then "Servers"

  2. Click "Deploy To New Server" at the top of the table

    Screenshot

  3. Select the "Operating System" that the server is running. This will adjust how the agent is deployed to the server (YUM or APT Repo)

  4. Then select which "Server Group" you would like to assign the server to. Server Groups are logical groupings of servers that share the same users, groups, privileges, SSH server settings and SSH keys. For example "Production Web Servers" would typically have the same user accounts and settings. Therefor grouping the servers together allows you to assign settings to the group as a whole instead of individual servers

  5. Now select the "Deployment Secret" you would like to use for this deployment. A Deployment Secret is simply a password that the Keystash agent will use to authenticate with your Keystash account. We recommend creating multiple Deployment Secrets and using a particular secret for a particular Server Group. For example if you had the Server Group called "Production Web Servers" you would create a Deployment Secret called "Production Web Servers" and you would only use that Deployment Secret for that Server Group.

    Note

    If a Deployment Secret is compromised then you would need to disable or delete it. This would mean that all servers that were deployed with the Deployment Secret would no longer be able to authenticate and synchronise with Keystash

  6. You can tell the Keystash agent to use a proxy server by clicking "Adjust advanced options". Provide the full details of the proxy server by giving it a detailed URL such as "https://proxy-server.example.com:8443"

  7. Lastly copy the "Deployment Command" and paste this into the terminal of your Linux server or add this to your automation tool such as Ansible or Chef. TIP: You can use the "copy" button that shows in the right hand corner of the Deployment Command when you hover the mouse over this section of the page

    Warning

    The Keystash agent will overwrite any user accounts that already exist on the server and in Keystash. The agent will also modify your SSHd and PAM configurations, therefor we strongly recommend you test your deployment on a new blank server first and only then on a live server.

  8. You can use this deployment command for multiple servers of the same Linux distribution. These servers will all use the same Deployment Secret and Server Group

Edit Servers

At any time you can change a server's Server Group assignment and description. To do this:

  1. Click "Server Management" and then "Servers"

  2. Click on "Edit" in the "Actions" field for the server you want to edit

    Screenshot

  3. Adjust the Server Group or Description as required

  4. Click "Save" to save your changes

Warning

When changing the Server Group assignment, all the users, groups, privileges, SSH server settings and SSH keys will adjust to the new Server Group settings. If a user has an active session on a server and their privileges are removed by the new Server Group then their active session will disconnect.

Note

The Server Edit view shows additional server information such as: Internal IP Addresses, Linux Distribution details and the Keystash Agent version.

Delete Servers

Once a server has been decommission in your environment you may want to clear it out of Keystash.

  1. Click "Server Management" and then "Servers"
  2. Click on "Delete" in the "Actions" field for the server you want to delete
  3. Click "Yes, please!" when prompted

Warning

Deleting a server that is still active with the Keystash agent running will simply re-create the server in Keystash. If you want to continue to have the server up and running but not connected to Keystash, then first uninstall the agent and then delete it from Keystash.

Server Status

Any server registered with Keystash will show one of the four following states. You can use these states to determine if the Server is correctly configured to work with Keystash and is actively synchronising users and SSH keys.

  • Connected: This means the server and the Keystash agent has correctly connected to Keystash within the last 5 minutes and has synchronised all changes to users, groups, permissions and SSH keys
  • Disconnected: This means the server and Keystash agent has not connected at all within the last 5 minutes and it is not synchronising any changes to users, groups, permissions and SSH keys. Either the server is off or the Keystash agent is failing to connect to the Keystash platform at https://server-api.keystash.io
  • Syncing: This means that the server and Keystash agent has attempted to connect to Keystash within the last 5 minutes but is either not up to date with the latest changes or is still busy synchronising the latest changes. Servers will typically not stay in this state for long, so refresh the list to determine if the server becomes Connected or Disconnected
  • Warning: This means that the server and Keystash agent has attempted to connect to Keystash within the last 5 minutes but there is an issue stopping it from fully synchronising the latest changes. Servers will typically not stay in this state for long so refresh the list to determine if the server becomes Connected or Disconnected

Export To CSV

You can export your full list of Servers with all associated details to a CSV file.

  1. Click "Server Management" and then "Servers"
  2. Click "Export To CSV" at the top of the table
  3. Your CSV export will begin and it will be offered as a normal file download

  4. Open the file in Microsoft Excel or Google Sheets (or similar tabular file editor). Google Sheets will automatically open the file correctly.

    Note

    Excel may not open the file correctly depending on your computers regional settings. See here to resolve this issue.

Clean Up Servers

This feature allows users to remove servers that have been in a disconnected state for an extended period. This helps to keep the server list manageable and ensures that only active servers are displayed.

  1. Select the Server Groups would you like to remove servers from
    • Use the dropdown menu to select the server groups you want to clean up. You can select one or multiple server groups.

  2. Specify the minimum duration that the servers have been in a disconnection state.

    • Enter the number of days a server must have been disconnected to be eligible for removal. The valid range is between 2 and 60 days.

    Screenshot

  3. A table will display the servers that will be removed based on your selections. The table includes the following columns:

    • Hostname: The hostname as set on the server.
    • Status: The status of the server (should be Disconnected).
    • ID: The unique ID that represents the server.
    • Location: The geographic location of the external IP address.
    • Provider: The provider or company that the external IP is registered to.
    • External IP: The external IP address detected by Keystash.
    • Server Group: The server group to which the server is assigned.
    • Created: The date and time the server was registered.

  4. Click the Clean Up button to remove the selected servers.

Warning

Removing servers is irreversible. Ensure that the servers listed are indeed the ones you want to remove.

Example Usage

  • Suppose you want to clean up servers in the Staging Servers Group that have been disconnected for more than 30 days.
    • Select Staging Servers Group from the dropdown menu.
    • Enter 30 in the days field.
    • Review the list of servers in the preview table.
    • Click Clean Up to remove the listed servers.