added communities doc, trimmed readme, outsourced advanced topics (#540)

README.md

@@ -40,7 +40,7 @@ You can create your own infrastructure by setting up a supernode on a public ser
 1. Install the n2n package
 2. Edit `/etc/n2n/supernode.conf` and add the following:
    ```
-   -l=1234
+   -p=1234
    ```
 3. Start the supernode service with `sudo systemctl start supernode`
 4. Optionally enable supernode start on boot: `sudo systemctl enable supernode`
@@ -66,16 +66,6 @@ For Windows, MacOS and general building options, please check out [Building docu
 
 **IMPORTANT** It is generally recommended to use the [latest stable release](https://github.com/ntop/n2n/releases). Please note that the current _dev_ branch usually is not guaranteed to be backward compatible neither with the latest stable release nor with previous _dev_ states. On the other hand, if you dare to try the bleeding edge features, you are encouraged to compile from _dev_ – just keep track of sometimes rapidly occuring changes. Feedback in the _Issues_ section is appreciated.
 
-## Running edge as a Service
-
-edge can also be run as a service instead of cli:
-
-1. Edit `/etc/n2n/edge.conf` with your custom options. See `/etc/n2n/edge.conf.sample`.
-2. Start the service: `sudo systemctl start edge`
-3. Optionally enable edge start on boot: `sudo systemctl enable edge`
-
-You can run multiple edge service instances by creating `/etc/n2n/edge-instance1.conf` and
-starting it with `sudo systemctl start edge@instance1`.
 
 ## Security Considerations
 
@@ -88,20 +78,15 @@ AES encryption by default. Other ciphers can be chosen using the `-A_` option.
 
 A benchmark of the encryption methods is available when compiled from source with `tools/n2n-benchmark`.
 
-The header which contains some metadata like the virtual MAC address of the edge nodes, their IP address
+The header which contains some metadata like the virtual MAC address of the edge nodes, their IP address, their real 
-and the community name optionally can be encrypted applying `-H` on the edges.
+hostname and the community name optionally can be encrypted applying `-H` on the edges.
 
-## Virtual Network Device Configuration
 
-The [TAP Configuration Guide](https://github.com/ntop/n2n/blob/dev/doc/TapConfiguration.md) contains hints on various settings that can be applied to the virtual network device, including IPv6 addresses as well as notes on MTU and on how to draw IP addresses from DHCP servers.
+## Advanced Configuration
 
-## Routing the Traffic
+More information about communities, routing, traffic restrictions and on how to run an edge as 
+a service is available in the [more detailed documentation](doc/Advanced.md).
 
-Reaching a remote network or tunneling all the internet traffic via n2n are two common tasks which require a proper routing setup. n2n supports routing needs providing options for packet forwarding (`-r`) including broadcasts (`-E`) as well as temporarily modifying the routing table (`-n`). Details can be found in the [Routing document](doc/Routing.md).
-
-## Traffic Restrictions
-
-It is possible to drop or accept specific packet transmit over edge network interface by rules. Rules can be specify by (`-R rule_str`) multiple times. Details can be found in the [Traffic Restrictions](doc/TrafficRestrictions.md).
 
 ## Contribution
 

doc/Advanced.md

@@ -0,0 +1,33 @@
+# Advanced Configuration
+
+
+## Running edge as a Service
+
+edge can also be run as a service instead of cli:
+
+1. Edit `/etc/n2n/edge.conf` with your custom options. See `/etc/n2n/edge.conf.sample`.
+2. Start the service: `sudo systemctl start edge`
+3. Optionally enable edge start on boot: `sudo systemctl enable edge`
+
+You can run multiple edge service instances by creating `/etc/n2n/edge-instance1.conf` and
+starting it with `sudo systemctl start edge@instance1`.
+
+
+## Communities
+
+You might be interested to learn some [details about Communities](doc/Communities.md) and understand how to limit supernodes' services to only a specified set of communities.
+
+
+## Virtual Network Device Configuration
+
+The [TAP Configuration Guide](https://github.com/ntop/n2n/blob/dev/doc/TapConfiguration.md) contains hints on various settings that can be applied to the virtual network device, including IPv6 addresses as well as notes on MTU and on how to draw IP addresses from DHCP servers.
+
+
+## Routing the Traffic
+
+Reaching a remote network or tunneling all the internet traffic via n2n are two common tasks which require a proper routing setup. n2n supports routing needs providing options for packet forwarding (`-r`) including broadcasts (`-E`) as well as temporarily modifying the routing table (`-n`). Details can be found in the [Routing document](doc/Routing.md).
+
+
+## Traffic Restrictions
+
+It is possible to drop or accept specific packet transmit over edge network interface by rules. Rules can be specify by (`-R rule_str`) multiple times. Details can be found in the [Traffic Restrictions](doc/TrafficRestrictions.md).

doc/Communities.md

@@ -0,0 +1,79 @@
+# Communities
+
+
+## Names
+
+As communities designate virtual networks, they must be distingushable from each other. Its their name that makes them distinguishable and which therefore should be unique per network. The community name is composed of 15 byte-sized characters and it internally always is terminated by an additional zero character totalling up to 16 characters. Hence, the zero character cannot be part of the regular community name. There are some other characters that cannot be used, namely `. * + ? [ ] \`.
+
+To make full use of character space, hex values could be used, e.g. from Linux bash applying the `edge … -c $(echo -en '\x3a\x3b\x4a\x6a\xfa')…` command line syntax. If used with a configuration file, the bytes must be directly filled as characters into a corresponding `-c=:;Jjþ` line.
+
+
+## Restrict Supernode Access
+
+By default, a supernode offers its service to all communities and allows them to connect. If a self-setup supernode shall handle certain communities only, the supernode can be given a list of allowed communities. This list is a simple text file containg the allowed community names, one per line:
+
+```
+ # community.list (a text file)
+ -----------------------------------------------------
+ myCommunity
+ yourCommunity
+```
+
+This file is provided to the supernode through the `-c community.list` command line parameter. This example would allow the supernode to only accept connections from communities called "myCommunity" and "yourCommunity", these are fixed-name communities.
+
+
+## Somewhat Flexible Community Names
+
+If you want to allow all community names from a certain name range, e.g. from "myCommunity00" to "myCommunity99", the `community.list` file (or whatever you name it) could look as follows:
+
+```
+ # community.list (a text file)
+ -----------------------------------------------------
+ myCommunity[0-9][0-9]
+```
+
+Advanced users recognize the so called regular expression. To prevent users from stop reading, the author did not dare to name this section "Regular Expressions". Anyway, community names can be provided as regular expressions using the following placeholders:
+
+```
+ '.'        Dot, matches any character
+ '*'        Asterisk, match zero or more of previous element (greedy)
+ '+'        Plus, match one or more of previous element (greedy)
+ '?'        Question, match zero or one (non-greedy)
+ '[abc]'    Character class, match if one of {'a', 'b', 'c'}
+ '[^abc]'   Inverted class, match if NOT one of {'a', 'b', 'c'}  (feature is currently broken)
+ '[a-zA-Z]' Character ranges, the character set of the ranges { a-z | A-Z }
+ '\s'       Whitespace, \t \f \r \n \v and spaces
+ '\S'       Non-whitespace
+ '\w'       Alphanumeric, [a-zA-Z0-9_]
+ '\W'       Non-alphanumeric
+ '\d'       Digits, [0-9]
+ '\D'       Non-digits
+```
+
+Knowing this, we can as well express the exemplary `community.list` above the following way:
+
+```
+ # community.list (a text file)
+ -----------------------------------------------------
+ myCommunity\d\d
+```
+
+Also, as the `. * + ? [ ] \` characters indicate parts of regular expressions, we now understand why those are not allowed in fixed-name community names.
+
+
+## Header Encryption
+
+By default, the community name is transmitted in plain witch each packet. So, a fixed-name community might keep your younger siblings out of your community (as long as they do not know the community name) but sniffing attackers will find out the community name. Using this name, they will be able to access it by just connecting to the supernode then.
+
+[Header encryption](doc/Crypto.md#header) can be enabled to prevent plain transmission. It is important to understand that header encryption, if enabled, only works on fixed-name communities. It will not work on communitiy names described by regular expressions.
+
+On the other hand, the provision of fixed-name communities blocks all other, non-listed communities. To allow a mixed operation of certain encrypted and hence fixed-name communities along with all other open communities, the following "trick" can be applied:
+
+```
+ # community.list (a text file)
+ -----------------------------------------------------
+ mySecretCom
+ .*
+```
+
+This is not really a trick but just making use of a very permissive regular expression at the second line.