Merge pull request #510 from reynico/acls-doc

docs/acls.md

@@ -5,12 +5,16 @@ ACL's are the most useful).
 
 We have a small company with a boss, an admin, two developers and an intern.
 
-The boss should have access to all servers but not to the users hosts. Admin
+The boss should have access to all servers but not to the user's hosts. Admin
 should also have access to all hosts except that their permissions should be
 limited to maintaining the hosts (for example purposes). The developers can do
-anything they want on dev hosts, but only watch on productions hosts. Intern
+anything they want on dev hosts but only watch on productions hosts. Intern
 can only interact with the development servers.
 
+There's an additional server that acts as a router, connecting the VPN users
+to an internal network `10.20.0.0/16`. Developers must have access to those
+internal resources.
+
 Each user have at least a device connected to the network and we have some
 servers.
 
@@ -19,22 +23,19 @@ servers.
 - app-server1.prod
 - app-server1.dev
 - billing.internal
+- router.internal
 
-## Setup of the network
+![ACL implementation example](images/headscale-acl-network.png)
 
-Let's create the namespaces. Each user should have his own namespace. The users
+## ACL setup
-here are represented as namespaces.
 
-```bash
+Note: Namespaces will be created automatically when users authenticate with the
-headscale namespaces create boss
+Headscale server.
-headscale namespaces create admin1
-headscale namespaces create dev1
-headscale namespaces create dev2
-headscale namespaces create intern1
-```
 
-We don't need to create namespaces for the servers because the servers will be
+ACLs could be written either on [huJSON](https://github.com/tailscale/hujson)
-tagged. When registering the servers we will need to add the flag
+or Yaml. Check the [test ACLs](../tests/acls) for further information.
+
+When registering the servers we will need to add the flag
 `--advertised-tags=tag:<tag1>,tag:<tag2>`, and the user (namespace) that is
 registering the server should be allowed to do it. Since anyone can add tags to
 a server they can register, the check of the tags is done on headscale server
@@ -70,6 +71,14 @@ Here are the ACL's to implement the same permissions as above:
 
     // interns cannot add servers
   },
+  // hosts should be defined using its IP addresses and a subnet mask.
+  // to define a single host, use a /32 mask. You cannot use DNS entries here,
+  // as they're prone to be hijacked by replacing their IP addresses.
+  // see https://github.com/tailscale/tailscale/issues/3800 for more information.
+  "Hosts": {
+    "postgresql.internal": "10.20.0.2/32",
+    "webservers.internal": "10.20.10.1/29"
+  },
   "acls": [
     // boss have access to all servers
     {
@@ -108,6 +117,16 @@ Here are the ACL's to implement the same permissions as above:
         "tag:prod-app-servers:80,443"
       ]
     },
+    // developers have access to the internal network through the router.
+    // the internal network is composed of HTTPS endpoints and Postgresql
+    // database servers. There's an additional rule to allow traffic to be
+    // forwarded to the internal subnet, 10.20.0.0/16. See this issue
+    // https://github.com/juanfont/headscale/issues/502
+    {
+      "action": "accept",
+      "users": ["group:dev"],
+      "ports": ["10.20.0.0/16:443,5432", "router.internal:0"]
+    },
 
     // servers should be able to talk to database. Database should not be able to initiate connections to
     // applications servers