# Servers and health

## 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

1. Create the record:

```bash
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.

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

```bash
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

```bash
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

```bash
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](/developers/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](/developers/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](/developers/backups-and-restore)). Everything is in [Servers](/developers/api-servers) and [Recipes](/developers/api-recipes).

## Removing a server

Not possible with the API. See [Deleting safely](/developers/deleting-safely).