Servers and health

Add and connect a server, watch its health and security, and manage firewall, databases, PHP and backups.

When to use this

You manage servers from code. Reads need servers:read; changes need servers:write (high risk). Many changes only work on servers pfcloud set up itself, not on adopted servers (servers that already ran live sites). Those answers say so.

Add and connect a server

Create the record:

curl -s -X POST $MYFORGE/servers \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: add-server-1" -H "Content-Type: application/json" \
  -d '{"name":"web-1","ip_address":"203.0.113.10","ssh_port":22}'

The same checks as the dashboard apply: plan limit, and the IP must not already be in the team or waiting to be purged. The server is saved as pending. The answer includes pfcloud's public key and the command to authorize it. GET /servers/{server}/authorized-key shows them again. Tokens limited to certain servers cannot add servers.

A person (or your own automation on the server) puts the key in authorized_keys for root.
Start the connection:

curl -s -X POST $MYFORGE/servers/SERVER_ID/connect -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: connect-1"

pfcloud inspects the server read-only, then provisions a fresh one (Nginx, PHP, database, firewall) or adopts one that already runs sites. Poll GET /servers/{server}: status goes connecting, then provisioning, then active (set up by pfcloud) or adopted (existing server), or failed. GET /servers/{server}/runs and .../runs/{run} show the script output.

Use POST /servers/{server}/rescan to read the server again, and POST /servers/{server}/reboot to restart it (high risk: sites go down for a minute).

Health

GET /servers/{server}/health: resources, issues found, live agent.
PUT /servers/{server}/monitoring turns the health collector on or off; PUT /servers/{server}/agent installs or removes the live metrics agent. Both depend on your plan.

Security report

curl -s -H "Authorization: Bearer $TOKEN" $MYFORGE/servers/SERVER_ID/security
curl -s -X POST -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: sec-1" $MYFORGE/servers/SERVER_ID/security-checks

The report has a score and findings (each with severity, title, detail and a fix). A check may start once every 10 minutes per server. Wait a minute, then read the report. To apply a one-click fix for a finding that has one: POST /servers/{server}/security-fixes with {"finding":"FINDING_ID"}. Fixes work on servers pfcloud set up and run the check again afterwards.

Firewall

curl -s -X POST $MYFORGE/servers/SERVER_ID/firewall-rules \
  -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: fw-1" -H "Content-Type: application/json" \
  -d '{"name":"Redis from office","port":"6379","protocol":"tcp","source":"203.0.113.0/24"}'

port is a number or a range like 6000:6010; source is any, an IP or a range. SSH, HTTP and HTTPS can never be closed. DELETE /servers/{server}/firewall-rules/{rule} closes a port. Do not open database ports to any.

Databases

POST /servers/{server}/databases with name and optional user creates a database and its user. The answer holds the password once. pfcloud never stores it. To drop a database you must use a deletion request: Deleting safely.

PHP

GET /servers/{server}/php: versions and settings.
POST /servers/{server}/php/versions: install a version.
PUT /servers/{server}/php/{version}: change limits and OPcache settings.
POST /servers/{server}/php/{version}/extensions and DELETE .../extensions/{extension}.
POST /servers/{server}/php/refresh: read the settings again.

New Ubuntu releases may not have every PHP version in their packages yet. If an install fails with a missing version, pick one the server offers. See Troubleshooting.

Other server calls

Services (GET /servers/{server}/services, POST .../services/{service}/restart), languages and Docker (POST .../languages, POST .../docker), SSH keys, recipes (/recipes), server backups (see Backups and restore). Everything is in Servers and Recipes.

Removing a server

Not possible with the API. See Deleting safely.