Create server rules

The Rules tab, under More on the server's page, holds a server's automation rules. A rule names a trigger, optional conditions and the actions to take. When the trigger fires and every condition holds, we run the actions in order.

A rule can act at set times, as a schedule does. It can also act after a crash, when memory, disk or CPU use reaches a level, or when a new version of the server's software is out. To take a snapshot at set times, use a schedule.

• On a server someone shared with you, the owner must have given you the Manage rules permission.
• A Resource use rule needs a limit on what it watches. When the server's plan sets no memory, disk or CPU limit, the form lists that choice as Memory (no limit), Disk (no limit) or CPU (no limit), and you cannot choose it.

1. In the dashboard, go to App Deployment and open the server, then the Rules tab.

2. Select New rule…. A page opens with the heading Create a rule. If you leave it after typing, we ask Leave without saving? first. A summary beside the form, What it does, reads the rule back in words as you build it.

3. Under Name, enter a name, for example Restart every night.

4. Under When it acts, choose a Trigger, which says what makes the rule act:

   • Schedule acts at the times you set, in UTC. Under Repeat, choose Every hour, Every day or Every week, then the Day (UTC), Hour (UTC) and Minute where the form asks for them. For any other pattern, choose Custom (cron) and enter five fields in Cron expression, such as 0 4 * * * for 04:00 UTC every day. The form shows the schedule in words under the fields, such as Every day at 04:00 UTC.
   • Crash acts when the server stops or restarts on its own.
   • Resource use acts when use reaches a level. Under Watch, choose Memory, Disk or CPU, then enter the level in Level as a percentage of the server's limit, from 1 to 100. For CPU we use the average over the last 15 minutes, so a short burst does not count.
   • Software update available acts when a newer version of the server's software is out.

5. To limit when the rule acts, go to Conditions, select Add condition and choose one under Condition:

   • Server status, with the state the server must be in under Status: Running, Starting, Stopping or Offline.
   • Time of day, with the hours under From (UTC) and Until (UTC). 02:00 to 05:59 limits the rule to those four hours. The window cannot cross midnight UTC.
   • Newer version available, which holds when the installed version is not the newest. The form offers it with the Software update available trigger only.

   Add as many as you need. The rule acts only when every condition is true, and with none it acts every time the trigger fires. To remove a condition, select the bin button beside its heading, such as Condition 1.

6. Under Actions, choose what the rule does under Action:

   • Run a console command, with the command in Command, for example say Restarting for an update in 5 minutes.
   • Send a power signal, with Start, Stop, Restart or Kill under Signal.

   Select Add action for another action. We run them in order, and a rule needs at least one.

7. Back under Name, leave Enabled ticked to switch the rule on, or clear it to save it switched off.

8. Select Create rule.

We check every server's rules once a minute, so a rule acts within about a minute of its trigger. All times are in UTC.

When a schedule time or a resource level arrives and a condition does not hold, the rule skips it and waits for the next one. A new version waits for the conditions instead, so a rule that restarts for an update between 02:00 and 05:59 UTC acts in the next window.

No rule acts while the server installs, moves to another machine or is suspended, while we have locked it, or after its install failed.

1. On the Rules tab, select the rule's name. A page opens with the heading Edit rule and the same sections as Create a rule.
2. Change what you need, then select Save rule.

A rule that holds something the form cannot write, such as an older trigger or a recipe, opens with This rule cannot be edited here. Saving it through the form would change what it does. Delete it and make a new rule instead.

• To turn a rule off or on, use the switch in its Enabled column.
• To delete a rule, select the bin icon at the end of its row, then Delete rule.

The dashboard confirms a new rule with Rule created. and a changed one with Rule saved., then returns to the list. The list shows each rule's name, its Trigger, when you created it and whether it is enabled. Under the name, the rule reads in words:

• when it acts, such as Every day at 04:00 UTC, When memory use reaches 90% or When the server stops or restarts on its own;
• its actions, such as Restart the server, then run say Back soon;
• its conditions, which read Only if followed by each one, such as Only if the server is offline and between 02:00 and 05:59 UTC;
• when it last acted, as Last fired with the date and time, or Never fired.

Rules created before this form can name other triggers, such as Manual or Console line, and other actions, such as running a recipe. They stay in the list with their trigger and actions in words, and you can turn them off or delete them. A rule whose trigger we do not run reads Rules with this trigger never act. Make a new rule and delete this one. A condition of a kind the form does not offer reads Ignores 1 older condition, because the rule acts as if it were not there. A rule that updates the server's software shows Rules no longer update software. Update from the Updates tab, and delete this rule. Install newer versions from the Updates tab instead.

Enter five fields, such as 0 4 * * * for 04:00 UTC every day.

The Cron expression does not have five fields. Enter the minute, hour, day of the month, month and day of the week, separated by spaces.

Enter a whole number from 1 to 100.

Level is empty or is not a whole number from 1 to 100.

Enter the command to run, such as say Restarting soon.

A Run a console command action has an empty Command. Enter the command, or remove the action.

Choose an end after the start. A window cannot cross midnight UTC.

The Until (UTC) hour is before the From (UTC) hour. For hours that cross midnight, create two rules, one each side of midnight.

This server has no memory limit, so this rule never acts.

The rule watches memory, disk or CPU, and the server's plan sets no limit for it, so there is no level to reach. Delete the rule, or create one that watches another resource.

This rule has no schedule, so it never acts. Make a new rule and delete this one.

The rule was saved without what its trigger needs, a schedule or a level. The same goes for This rule watches nothing and This rule has no level to reach. Create the rule again with the form, and delete the old one.

A rule reads Never fired

Check its conditions first: a schedule time or a resource level that arrives while a condition does not hold is skipped. Check that the switch in Enabled is on, and that the server was not installing, moving or suspended at the time.

Could not create the rule

We refused the rule. The message under the title gives the reason, and the page keeps what you entered. A rule you change reads Could not save the rule.

Could not update the rule or Could not delete the rule

The message after it gives the reason. Rule not found means someone deleted the rule, or it belongs to another server. Reload the tab to see the current list.

Insufficient permissions

On a server someone shared with you, ask the owner for the Manage rules permission.

• Schedule server tasks runs commands, power actions and snapshots at set times.
• Install server updates installs newer versions of the server's software.
• Share a server with other users explains the Manage rules permission.

Create a rule with POST /api/v1/client/servers/{uuid}/rules. The body takes name, trigger_type, trigger_config (an object, default {}), conditions (a list, or null for none), actions (a list) and enabled (default true):

curl -X POST https://api.coritan.com/api/v1/client/servers/$SERVER/rules \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Restart every night", "trigger_type": "schedule", "trigger_config": {"cron": "0 4 * * *"}, "conditions": [{"type": "server_status", "value": "running"}], "actions": [{"type": "command", "command": "say Restarting in 1 minute"}, {"type": "power", "action": "restart"}]}'

Each trigger reads its own trigger_config:

A schedule rule without a valid cron expression answers 422 with A schedule rule needs a cron expression with five fields, such as 0 4 * * * for 04:00 UTC every day. A resource rule answers 422 with A resource rule watches cpu, memory or disk. or A resource rule needs a level from 1 to 100 percent.

Each condition is an object with a type:

Each action is an object with a type:

The dashboard does not offer an update_software action, and the API refuses one with a 422 that names the actions it takes.

The response (201) is the rule, with uuid, name, trigger_type, trigger_config, conditions, actions, enabled, created_at, updated_at and last_triggered_at, the time the rule last acted, or null before it has.

Both answer 404 with Rule not found for a rule that does not exist or belongs to another server.

Creating, changing and deleting need settings.automation. Any user on the server can list its rules.