# Core concepts

Servers, environments, plans, steps, tools, runs and modules, and how each one relates to the next.

Source: https://opafra.com/docs/concepts

---

Opafra has seven nouns. A **plan** is an ordered list of **steps**; each step calls a
**tool**; a plan targets **servers**, usually through an **environment**; executing one
produces a **run**; and a sequence worth reusing becomes a **module**.

## Servers

A server is a host Opafra can reach over SSH. Registering one stores its address, the
user to connect as, and which credential to use. It does not install anything on the
machine, and it does not hold a copy of your key material in the plan.

What Opafra records about a host is what it observed: the OS family, the SSH version,
and whether the last connection check succeeded.

## Environments

An environment is a named group of servers, and it is where policy lives. Targeting a
plan at `production` rather than at three hostnames means the plan keeps working when
the fourth host is added.

An environment can be marked **protected**, which is what turns on an approval gate for
every plan that touches it. That is a property of the environment, not of the plan, so
it applies whether or not whoever wrote the plan thought about it.

## Plans and steps

A plan is an ordered list of steps plus the targets to run them against. A step names a
tool and the arguments to call it with.

```yaml title="the shape of a plan"
name: Patch nginx
targets:
  - production
steps:
  - name: Back up the current config
    tool: file.backup
    args:
      path: /etc/nginx/nginx.conf
  - name: Upgrade the package
    tool: apt.upgrade
    args:
      package: nginx
```

Plans can be written by hand, drafted by the composer from a request, or synced from a
git repository.

## Tools

A tool is a named operation with declared arguments, in a namespace: `file.lineinfile`,
`apt.upgrade`, `systemd.start`. Tools are the reason a plan can be dry run and can report
what changed, and they are what a step calls.

Every tool declares what it supports: whether it can be previewed, whether it needs
privilege, and the conditions under which it reports changed rather than unchanged. The
[tool catalogue](/docs/reference/tools) lists all of them.

A step can also run a raw command or an uploaded script. That is deliberately available
and deliberately weaker: a raw command cannot be previewed as precisely, and Opafra
cannot tell you what it changed.

## Runs

Executing a plan produces a run. A run records what was asked for, what was drafted, who
approved it if an approval was required, what each step did on each host, and the result.

A **dry run** is a run that stops short of changing anything. It connects to each host
and reports what would happen, per host, so the differences between hosts surface before
the real run rather than during it.

## Modules

A module is a sequence of steps extracted so it can be reused with parameters. When the
same four steps appear in six plans, that is a module, and fixing it once fixes all six.

## How they fit together

A request becomes a plan of steps calling tools. The plan targets an environment of
servers. Running it produces a run, which is dry first if you want to see what it would
do. If the environment is protected, an approver lets it through before anything changes.
Whatever happens is on the audit log.

## Next steps

- [Quickstart](/docs/quickstart) to do all of that once, on one host
- [Approval gates](/docs/running/approval-gates) for how protected environments behave