servd

Documentation

Documentation > Common Tasks >

Start an SSH Session

You can start an SSH session within your project and connect to it via an SSH client in order to explore your project's filesystem in real time.

Any changes made to the filesystem will not persist indefinitely! See the Limitations section below for more information.

Starting an SSH Session #

  1. Navigate to your project's Access Control page in the Servd dashboard.

  2. In the SSH Sessions panel, click the "Add New Session" button.

    A modal will open allowing you to select some options for your new session. Select or enter a Public Key, Connecting IP and Persistence option. Then click Start New Session.

    • Public Key: This is the public portion of the key that you would like to use for authentication when using this SSH Session. You should have the associated private key available on your local machine.
    • Connecting IP: This is the IP address that your SSH connection will be originating from. Normally this will be your local machine's public internet IP, however if you are setting up a connection for a remote system to use, it will be the public internet IP of the remote system. This is added to a firewall rule to allow access.
    • Persistence: By default all SSH Sessions last for 24 hours only to ensure a zero-trust access policy is maintained. Projects can also have a single persistent session which lasts until it is manually removed from our dashboard. This should only be used for systems/automated access, I.E if an external platform needs direct access to the project's database via tunnelling.

  3. A background task will run to update your project's configuration. Once complete, you can use the options in the "SSH Connection" section to generate a connection string that you can copy into a terminal running on your local machine.

    Alternatively, you can use the same details provided in the connection string to connect using a GUI SSH client.

Stopping an SSH Session #

It is best practice to stop an SSH session whenever you have finished using it. To do so simply click the X icon next to the relevant SSH Session in our dashboard. This will immediately end the session and remove the associated Connecting IP from the Firewall access rule.

Frequently Used SSH Keys #

It is common to use a single SSH key pair to authenticate yourself in multiple contexts. Rather than requiring you to enter your personal public key every time you want to start a new SSH Session, you can associate one or more keys with your Servd User account. These will then appear as quick selection options when starting an SSH Session for any project that you have access to.

To add a public SSH key to your Servd User, visit the User Settings page and enter it into the SSH Keys panel along with a nickname (which will be used to reference it throughout our dashboard). Once saved it will be selectable from any project's SSH Sessions panel when creating a new session.

Limitations #

  • Any changes made to the filesystem will not persist indefinitely! Servd uses ephemeral filesystems to keep your project secure and allow features like full-filesystem rollbacks, but this also means any changes you make will be lost whenever you deploy a new bundle.
  • Changes you make will only be present on one of potentially several load balanced instances.
  • If you are attempting to find logs on a specific host, you might need to connect to your session multiple times until the host you are interested in is selected as the target for the connection.
  • You will be connected as the www-data user. This user will be able to perform all of the operations normally executed by PHP and can run ./craft CLI commands, but will not be able to install additional software or make changes to system files.
  • It is strongly recommended that you do not run any composer commands which might modify the filesystem. These changes will not persist across bundle deployments, but any database data changes which occur as a result (such as with a Craft update) will persist, potentially resulting in a broken project state.

SSH Tunnelling / Direct Database Access #

You can connect directly to a project's database by using tunnelling over your SSH sessions. This allows you to assign a port on your local machine which forwards traffic over the SSH connection to a service running at the SSH Session's destination.

You can select the 'Include database port forward' option in the 'SSH Connection' section to include a port forward in your SSH Connection string.

For more details on accessing the database in this way, see the Connect to the Database documentation.