Peerlify

Write your first rule

Replace the default allow-all rule with a few narrow rules, test them before saving, and roll out without locking yourself out.

Updated · ·By Ivan Vyshniak

Nothing on this page changes with your selection.

A new network starts with a single Default allow all rule. This guide replaces it with three narrow rules:

  • Admins can SSH into servers.
  • Anyone can reach the web servers on ports 80 and 443.
  • App servers can reach the database on port 5432.

Everything else becomes denied.

Before you start

  • You need the Owner or Admin role. A Network admin can write the rules, but needs an Owner, Admin or IT admin to tag the devices, and must be a manager of each tag. See Members and roles.
  • Decide which tags your rules will use. This example uses server, web, app and db.

1. Create the tags

  1. In the console, open Access, then the Tags tab.
  2. Type a name under New tag and click Add tag. Tag names may contain lowercase letters, digits and dashes.
  3. Repeat for each tag.

Network admins and tags

A Network admin can create tags but, by default, is not a manager of them, and can't save a rule that newly refers to a tag they don't manage. The save fails with "You don't manage the tag". Ask an Owner or Admin to add you as a manager. See Tags, groups and roles.

2. Tag your devices

  1. Open Devices.
  2. In a device's row, open the ⋯ menu and choose Edit tags.
  3. Add the tags and save.

Tagging a device turns it into a shared resource: it is no longer tied to the person who signed it in. See Devices.

3. Write the rules

Open Access → Rules. Rules are evaluated top to bottom, and the first match wins.

  1. Click Add rule and fill in:
    • Name: Admins SSH to servers
    • Action: Accept
    • Source: group:admins
    • Destination: tag:server
    • Ports: 22
    • Protocol: tcp
  2. Add the other two rules the same way.
  3. In Access → Groups, add group:admins with the email addresses of your admins.

New rules are added below Default allow all. Leave it there and enabled for now: as the first rule, it still allows everything, so nothing breaks while you set up. You'll turn it off in step 5.

In the Advanced tab, the new parts look like this (other entries omitted):

Policy (excerpt)json
"rules": [
  { "name": "Default allow all", "action": "accept", "…": "…" },
  { "name": "Admins SSH to servers", "action": "accept",
    "source": ["group:admins"], "destination": ["tag:server"],
    "ports": ["22"], "protocol": ["tcp"] },
  { "name": "Everyone reaches the web tier", "action": "accept",
    "source": ["*"], "destination": ["tag:web"],
    "ports": ["80", "443"], "protocol": ["tcp"] },
  { "name": "App servers reach the database", "action": "accept",
    "source": ["tag:app"], "destination": ["tag:db"],
    "ports": ["5432"], "protocol": ["tcp"] }
],
"groups": {
  "group:admins": ["alice@example.com", "bob@example.com"]
}

Two mistakes to avoid

  • Write ports and protocols as strings. "ports": ["22"] restricts the rule to port 22. "ports": [22] (a number) is discarded when you save, and a rule with no ports applies to every port.
  • Keep the object form. Pasting a bare array of rules into the Advanced tab is accepted, but it replaces the whole document and deletes your groups, tests and shadowing rules.

4. Add tests

Tests run every time the policy is saved, including restores. If any test fails, the save is refused and the editor switches to the Tests tab.

In Access → Tests, click Add test and fill in:

  • Source: who the test is about, for example group:admins.
  • Must be allowed: destinations that must be reachable, written as a selector with an optional :port, for example tag:server:22.
  • Must be denied: destinations that must not be reachable, for example tag:db:5432.

Name the port in each destination. tag:db:* doesn't mean "any port": it only checks rules that allow every port.

Add two tests now, for the connections that must work:

Tests (Advanced tab)json
"tests": [
  { "name": "admins reach servers over SSH", "src": "group:admins",
    "proto": "tcp", "accept": ["tag:server:22"], "deny": [] },
  { "name": "app servers reach the database", "src": "tag:app",
    "proto": "tcp", "accept": ["tag:db:5432"], "deny": [] }
]

Click Run tests to check the unsaved policy without saving it, then click Save rules on the Rules tab. Tests that check something must be denied would fail at this point, because Default allow all still allows everything; you'll add one in step 5.

Tests compare selectors as text

The test runner doesn't look up which devices carry a tag or who owns a device. It matches the selectors in your tests against the selectors in your rules as written, so use the same form in both: if a rule says tag:db, test against tag:db, not a device's IP. A group: source is expanded to its members. The protocol (proto) can only be set in the Advanced tab; without it, a rule matches the test whatever its protocol list says.

5. Roll out

  1. On the Rules tab, switch Default allow all off with Disable rule.

  2. On the Tests tab, add a test for a connection that must now be denied:

    json
    { "name": "web tier can't reach the database", "src": "tag:web",
  "proto": "tcp", "accept": [], "deny": ["tag:db:5432"] }

  3. Save. If a test fails, the save is refused and the Tests tab shows which one; fix the rule or the test and save again.

  4. From a device, try the connections the rules should allow, for example ssh admin@100.100.0.12 from an admin's laptop to a server.

  5. Try a connection that should now be denied. It should time out.

If something breaks, switch Default allow all back on and save. The change reaches devices within about 10 seconds. Every save is kept in History, so you can also restore an earlier version.

Keep a way back in

Rules govern traffic between devices only. The console is never blocked by the policy, so you can always sign in to web.peerlify.com and restore a working version.

Next steps

Was this page helpful?