Skip to main content
Open console

Shell access

Logging in to an environment over SSH, copying files and databases in and out, and what the shell can and cannot reach.

10 min read

Every environment can be reached over SSH, into the container your site runs in. Use it to run drush, read a file your application wrote, or move a database.

Before you start

Add an SSH key to your account: Your keys on the environment's Shell access card, SSH keys on your account, or vallic ssh-key add. Keys belong to you, not to a team. One key reaches every environment you are allowed a shell on, across all your teams. Removing it removes it from all of them.

Accepted Refused
Ed25519 DSA
ECDSA (256, 384 or 521 bits) RSA under 2048 bits
RSA of 2048 bits or more Hardware security keys (sk- types)

Generate Ed25519 for a new key. A key can only be on one account. A new key reaches the machines within a minute or so of saving it.

With the Vallic CLI

The CLI works out the host, the port and the account for you, and gets the quoting right. Every other command, from deploying to domains, is on The Vallic CLI.

curl -fsSL https://raw.githubusercontent.com/Vallic/vallic-cli/main/installer.sh | bash
vallic login
vallic ssh staging A shell. vallic ssh staging -- drush cr runs one command
vallic mount upload staging ./files Copies a local directory into the public files directory
vallic mount download staging ./files And back down
vallic mount upload staging ./private --area private The same for private files, or a mount: --area mounts/<name>
vallic mount list staging Every area the environment has, by the name --area takes
vallic db import staging < dump.sql Replaces the database with a dump; --file reads one, gzip or not
vallic db dump staging Takes a copy of it, into a file named for the project and environment; --table takes part of it
vallic db export staging > dump.sql The same copy, as a stream for a pipeline
vallic db size staging How much the database holds, and its largest tables
vallic sql staging An interactive database prompt; -- 'SELECT …' runs one query
vallic tunnel staging db A local port onto the database, for a desktop client; see Tunnels

The Shell access card shows the most used: logging in, drush on Drupal or a database prompt otherwise, taking a copy of the database, and importing one. Import is shown only until production answers at a domain of your own.

The card adds --project with your project's machine name, as in vallic ssh production --project acme-webshop, so its commands work from any directory. Inside your project's checkout you can leave it off: the project comes from the git remote. Leave the environment's name off as well to pick the one tracking your current branch.

The installer checks the download against a checksum the platform publishes, and installs nothing if it does not match. The CLI uses the same keys and the same access as plain SSH.

With MorphGate

MorphGate, an SSH client for the desktop, signs in to Vallic Cloud and makes a host of every environment you can reach. An environment on several machines gets one host for each machine and worker, logging in the way vallic ssh does. A refresh keeps the list in step, and a shared vault gives your whole team the same list. See Connect Vallic Cloud in its docs.

It can put its key on your account for you. Its file browser and tunnels do not work on these hosts: use vallic mount and vallic tunnel.

Logging in

Plain SSH works without the CLI. The card shows the full command under Plain SSH:

ssh -p 2417 vc-t-acme@production.gwfdxo99.vallic.cloud
  • The host is the environment's platform hostname. Never use your own domain, which may be behind a CDN that does not carry SSH.
  • The port belongs to the project. Every environment of the project uses the same one, and it does not change. It is not 22, so pass -p, and -e 'ssh -p …' for rsync.
  • The user is your team's account on the machine, the same for everyone on the team. Your key decides which person you are.
  • Staging and development add the environment's name after the host: ssh -t -p 2417 vc-t-acme@staging.gwfdxo99.vallic.cloud staging. Keep the -t: without it the shell opens and shows nothing. For a command, put it after the name: … staging db-export. For rsync, pass it as --rsync-path='staging rsync'. Without a name where one is needed, the login is refused with the choices. Production needs none.

With several keys loaded, SSH may offer the wrong ones first and be turned away before it reaches the right one. Name the key:

ssh -o IdentitiesOnly=yes -i ~/.ssh/id_ed25519 -p 2417 vc-t-acme@production.gwfdxo99.vallic.cloud

Where you land

Inside the site's application container, as the user the site runs as, not on the machine. Your code, your files and your database are within reach. The host, other containers' internals and other customers are not.

Path What it is
/var/www/html/current The live release. Read-only
/mnt/files/public Your application's files. Writable, and what survives a release
/var/log/app Your application's own log files; see Logs

Make a fix in the repository: the release cannot be edited in place.

drush is your project's own, from its vendor/bin, so it is the version your site was built with. So is anything else your build puts in vendor/bin or bin. WP-CLI is not provided: add it to your build if your WordPress site needs it.

If the environment has never been deployed, there is nothing to log in to yet, and the shell says so.

Several machines, and workers

An environment on more than one machine (a dedicated one, or one with a service on a machine of its own) answers at one address: its front. Name the machine and the front carries the login on to it, with the same key. The Shell access card's Plain SSH section lists a line per machine. By hand it is ssh's ProxyCommand:

ssh -t -o ProxyCommand='ssh -p 2417 vc-t-acme@production.gwfdxo99.vallic.cloud jump web-2' -p 2417 vc-t-acme@web-2.production.gwfdxo99.vallic.cloud

Where the front runs no site of its own (a load balancer, or Varnish on its own machine), the card's plain login already goes on to the first web server.

A worker runs in a container of its own, named worker-<name>-<n> after the worker in vallic.yaml, for example worker-queue-1. Put its name after @ to open it instead of the site's: ssh -t … @worker-queue-1, on the worker machine where the environment has one. The CLI takes the short name and finds the machine: vallic ssh production --container queue-1. The card lists the workers. Asking for one that is not on that machine lists what is.

Copying files

Each environment keeps three separate directories. All of them outlive every deploy:

Directory What it holds
/mnt/files/public Files the web serves directly: Drupal's sites/default/files
/mnt/files/private Files served only through your application's access checks
/mnt/files/mounts/<name> The extra directories your vallic.yaml lists under mounts

Anything in public can be fetched by its URL: never copy private files there.

vallic mount upload and vallic mount download reach all three: public by default, the others with --area private or --area mounts/<name>. Without the CLI, rsync straight into the directory:

rsync -avz -e 'ssh -p 2417' ./files/ vc-t-acme@production.gwfdxo99.vallic.cloud:/mnt/files/public/
rsync -avz -e 'ssh -p 2417' ./private/ vc-t-acme@production.gwfdxo99.vallic.cloud:/mnt/files/private/

The other way round takes a copy out. scp works too. On a recent OpenSSH use scp -O: without it scp speaks SFTP. SFTP itself is not available, so a graphical SFTP client will not connect.

Databases

Three commands run in the database container, so the right client is always there:

Command Does
db-export A dump of the environment's database, to standard output
db-import Loads a dump from standard input
db-cli An interactive mysql or psql prompt

db-import replaces what is there, and on production that is your live site. Take a backup first.

From your own computer, over SSH:

ssh -p 2417 vc-t-acme@production.gwfdxo99.vallic.cloud db-export > dump.sql
ssh -p 2417 vc-t-acme@production.gwfdxo99.vallic.cloud db-import < dump.sql
Database What db-import does
PostgreSQL Empties the public schema, then loads the dump into it. A dump made anywhere, with or without --clean, comes out the same. Does nothing if no dump arrives
MariaDB or MySQL Replaces each table the dump carries, and leaves any other

To bring another environment's data into staging, Copy from another environment under Backups is usually the better route: it runs your sanitisation commands.

Tunnels to your services

vallic tunnel opens a port on your own computer that reaches one of your environment's services, so a desktop client can connect to it: a database tool, a Redis or Solr browser, curl against Varnish.

vallic tunnel staging db        # whichever database the stack runs, on 127.0.0.1:3306
vallic tunnel staging redis     # 127.0.0.1:6379
vallic tunnel staging solr      # http://127.0.0.1:8983/solr
vallic tunnel production db --port 13306
Service Name Local port
The database db (or mariadb, mysql, postgres) 3306, or 5432 for PostgreSQL
Redis or Valkey redis, valkey 6379
Memcached memcached 11211
Solr solr 8983
Meilisearch meilisearch 7700
RabbitMQ rabbitmq 5672
InfluxDB influxdb 8086
Vinyl Cache (Varnish) varnish 6081

--port chooses another local port, when the usual one is taken or you have tunnels to two environments open at once. Ctrl-C closes the tunnel.

The credentials are your environment's own. For the database:

vallic ssh staging -- printenv DB_NAME DB_USER DB_PASSWORD

A tunnel reaches only the service you name, of the environment you name, on its own port. It works where the service runs on the same machine as your site. Reach a database on a machine of its own with vallic sql and vallic db. Whoever may open a shell may open a tunnel: see Who can use it.

What is not allowed

No SSH port or agent forwarding. ssh -L and ssh -A are refused. Use vallic tunnel to reach a service from your computer.

A connection that stops answering is dropped after about three minutes. Five failed logins from one address within ten minutes blocks that address for an hour.

Keeping the port to your addresses

Your project's SSH port answers the internet, with keys only. To have it answer only your office or your VPN, list their addresses under Restricted server access. Find it under Security with the add-ons when you configure the project, or later on its Configuration page. One address or range per line, IPv4 or IPv6, up to 25. Listed at configuration, the port is kept to them from the first machine.

# The office, and the VPN everybody else uses
203.0.113.0/24
198.51.100.14
2001:db8:42::/48
  • With a list, the port answers those addresses and nobody else, on every machine your team has, for every environment of the project. It takes effect at the next firewall pass, a few minutes later.
  • Your own machines are always let in, and so are the platform's operators. Copying another environment's data in and moving a database to a new machine keep working.
  • It is an add-on: €9 a month for the project while the list holds an address, prorated. Emptying the list lets anyone connect again and takes it off the invoice.
  • Admins and Owners change it. The change is in the team's audit log.

The list covers your project's port only. The platform's own SSH port answers only its operators' networks, on every machine.

Who can use it

Developer and above, and Admin and above on production: a shell reads every secret the site runs with, and its database. On staging and development a Developer opens one whether the environment is protected or not. Viewers get no card and no access.

Access follows your role. A person narrowed to certain projects reaches only those. A suspended team loses shell access along with everything else above Viewer.

Every login is recorded on our side: who, from which address, to which environment, and for how long. What is typed inside a session is not. Each login also appears in the team's audit log, which Admins and Owners read, as Opened a shell on a machine, with the machine and the time.

Next

  • Logs: reading what your application wrote
  • Backups: before you import anything over production