update styling, add notes

docs/user-guide/tunnels.md

@@ -5,7 +5,7 @@ Overview
 --------
 
 `tunnels.conf` is designed to support multiple I2P tunnels. The configuration file must be located in 
-``~/.i2pd`` (per-user) or ``/var/lib/i2pd`` (system-wide).
+``~/.i2pd`` (per-user) or ``/var/lib/i2pd`` (system-wide) on Unix-based systems, and ``%APPDATA%/i2pd`` (per-user) on Windows.
 
 This file uses the .ini file format. It consists of multiple sections each with a unique name.
 
@@ -82,22 +82,25 @@ Each client tunnel must contain a few mandatory parameters, along with some opti
 
 Here is an example of a client tunnel:
 
-    [irc-out]
+```ini
-    type = client
+[irc-out]
-    address = 127.0.0.1
+type = client
-    port = 6668
+address = 127.0.0.1
-    destination = irc.ilita.i2p
+port = 6668
-    keys = irc.dat
+destination = irc.ilita.i2p
+keys = irc.dat
+```
 
 If *keys* is empty, transient keys will be created on every restart. If the keys file is not found, new keys will be created and stored into the specified file.
 If *keys* starts from *transient*, new keys will be created, but not stored into a file.
+
 Client tunnels might share the same local destination, if the keys file contains the same identity.
 
 Optional parameters:
 
 Option              | Description
 --------------------|--------------------
-address             | local interface tunnel binds to, '127.0.0.1' for connections from local host only, '0.0.0.0' for connections from everywhere. '127.0.0.1' by default.
+address             | local interface tunnel binds to, '127.0.0.1' for connections from local host only, '0.0.0.0' for connections from everywhere. '127.0.0.1' by default
 signaturetype       | signature type for new keys. 0 (DSA), 1 (ECDSA-P256), 7 (EDDSA), 11 (RedDSA). RSA signatures (4,5,6) are not allowed and will be changed to 7. 7 by default
 cryptotype          | crypto type for new keys. Experimental. Should be always 0
 destinationport     | connect to particular port at destination. 0 by default (targeting first tunnel on server side for destination)
@@ -112,26 +115,32 @@ Mnemonic: we serving some service to others in network
 
 Here is an example of a server tunnel:
 
-    [smtp-in]
+```ini
-    type = server
+[smtp-in]
-    host = 127.0.0.1
+type = server
-    port = 25
+host = 127.0.0.1
-    keys = smtp-in.dat
+port = 25
+keys = smtp-in.dat
+```
+
+If *keys* is empty, transient keys will be created on every restart. If the *keys* file is not found, new keys will be created and stored into the specified file.
 
-The file in *keys* must be present, and the LeaseSet of address from keys file will be published. 
+Destination address from *keys* file will be loaded and the LeaseSet of address will be published.
-The server tunnel must use its own local destination such as host 127.0.0.1 and port 80.
+The server tunnel must use its own destination such as host 127.0.0.1 and port 80.
+
+This tunnel type should be used for any protocol other than HTTP, even HTTP with SSL encryption (HTTPS).
 
 Optional parameters:
 
 Option              | Description
 --------------------|--------------------
-inport              | what port at local destination server tunnel listens to. Same as *port* by default.
+inport              | what port at local destination server tunnel listens to. Same as *port* by default
-accesslist          | list of comma-separated of b32 address (without .b32.i2p) allowed to connect. Everybody is allowed by default.  
+accesslist          | list of comma-separated of b32 address (without .b32.i2p) allowed to connect. Everybody is allowed by default
-gzip                | turns internal compression off if set to false. true by default.  
+gzip                | turns internal compression off if set to false. true by default
-signaturetype       | means signature type for new keys. 0 - DSA, 1- ECDSA-P256, 7 -EDDSA, 11 -RedDSA. 7 by default.  
+signaturetype       | means signature type for new keys. 0 - DSA, 1- ECDSA-P256, 7 -EDDSA, 11 -RedDSA. 7 by default
-cryptotype          | crypto type for new keys. Experimental. Should be always 0.
+cryptotype          | crypto type for new keys. Experimental. Should be always 0
-enableuniquelocal   | if true, connection to local address will look like 127.x.x.x where x.x.x is first 3 bytes of incoming connection peer's ident hash. true by default.  
+enableuniquelocal   | if true, connection to local address will look like 127.x.x.x where x.x.x is first 3 bytes of incoming connection peer's ident hash. true by default
-address             | IP address of an interface tunnel is connected to host from. Usually not used.   
+address             | IP address of an interface tunnel is connected to *host* from. Usually not used
 
 Server/http tunnels
 -------------------
@@ -141,11 +150,13 @@ must be assigned to the address provided in configuration. i2pd will also resolv
 
 Here's an example of an http tunnel:
 
-    [http-in]
+```ini
-    type = http
+[http-in]
-    host = 127.0.0.1  
+type = http
-    port = 80
+host = 127.0.0.1  
-    keys = our-website.dat
+port = 80
+keys = our-website.dat
+```
 
 Optional parameters:
 
@@ -158,8 +169,7 @@ ssl                 | use SSL connection to upstream server. `hostoverride` para
 Server/IRC tunnels
 -------------------
 
-IRC tunnels are supposed to connect to an IRC server through WEBIRC.  
+IRC tunnels are supposed to connect to an IRC server through WEBIRC. It replaces IP address (usually 127.0.0.1) to user's .b32 I2P address.
-It replaces IP address (usually 127.0.0.1) to user's .b32 I2P address.  
 
 Optional parameters:
 
@@ -175,34 +185,36 @@ There are 2 types of UDP tunnels: `udpclient` and `udpserver`
 
 `udpclient` forwards 1 local UDP endpoint to 1 remote I2P destination
 
-
+```ini
-    [openvpn-client-simple]
+[openvpn-client-simple]
-    type = udpclient
+type = udpclient
-    destination = something.b32.i2p
+destination = something.b32.i2p
-    port = 1194
+port = 1194
+```
 
 Option              | Description
 --------------------|--------------------
 destination         | the I2P destination of a udpserver tunnel, required parameter
 address             | IP address to bind local UDP endpoint to, defaults to `127.0.0.1`
 port                | port to bind local UDP endpoint to, required parameter
-gzip                | turns internal compression off if set to false. true by default.  
+gzip                | turns internal compression off if set to false. true by default
 
 `udpserver` forwards traffic from N I2P destinations to 1 local UDP endpoint
 
-    [openvpn-simple-server]
+```ini
-    type = udpserver
+[openvpn-simple-server]
-    keys = openvpn.dat
+type = udpserver
-    host = 127.0.0.1
+keys = openvpn.dat
-    port = 1194
+host = 127.0.0.1
+port = 1194
+```
 
 Option              | Description
 --------------------|--------------------
 address             | IP address to use for local UDP endpoints, defaults to `127.0.0.1`
-host                | IP address to forward traffic to, required parameter.
+host                | IP address to forward traffic to, required parameter
 port                | UDP port to forward traffic on, required parameter
-gzip                | turns internal compression off if set to false. true by default.  
+gzip                | turns internal compression off if set to false. true by default
-
 
 Socks proxy
 -----------
@@ -211,18 +223,19 @@ The SOCKS proxy interface can be defined in ``tunnels.conf``.
 
 Here's an example of a Socks proxy:
 
-    [alt-socks]
+```ini
-    type = socks
+[alt-socks]
-    address = 127.0.0.1
+type = socks
-    port = 14447
+address = 127.0.0.1
-    keys = socks-keys.dat 
+port = 14447
+keys = socks-keys.dat 
+```
 
 Option              | Description
 --------------------|--------------------
 address             | local address Socks proxy binds to, defaults to `127.0.0.1`
 port                | TCP port Socks proxy binds to
 
-
 I2CP parameters
 ---------------
 
@@ -250,42 +263,43 @@ i2cp.leaseSetClient.psk.nnn   | client name:client's PSK in base64, for authenti
 Other examples
 --------------
 
-    # outgoing tunnel sample, to remote service
+```ini
-    # mandatory parameters:
+# outgoing tunnel sample, to remote service
-    # * type -- always "client"
+# mandatory parameters:
-    # * port -- local port to listen to
+# * type -- always "client"
-    # * destination -- I2P hostname
+# * port -- local port to listen to
-    # optional parameters (may be omitted)
+# * destination -- I2P hostname
-    # * keys -- our identity, if unset, will be generated on every startup,
+# optional parameters (may be omitted)
-    #     if set and file missing, keys will be generated and placed to this file
+# * keys -- our identity, if unset, will be generated on every startup,
-    # * address -- local interface to bind
+#     if set and file missing, keys will be generated and placed to this file
-    # * signaturetype -- signature type for new destination. 0 (DSA/SHA1), 1 (EcDSA/SHA256) or 7 (EdDSA/SHA512)
+# * address -- local interface to bind
-    [IRC]
+# * signaturetype -- signature type for new destination. 0 (DSA/SHA1), 1 (EcDSA/SHA256) or 7 (EdDSA/SHA512)
-    type = client
+[IRC]
-    address = 127.0.0.1
+type = client
-    port = 6668
+address = 127.0.0.1
-    destination = irc.ilita.i2p
+port = 6668
-    keys = irc-keys.dat
+destination = irc.ilita.i2p
-    #
+keys = irc-keys.dat
-    # incoming tunnel sample, for local service
+#
-    # mandatory parameters:
+# incoming tunnel sample, for local service
-    # * type -- "server" or "http"
+# mandatory parameters:
-    # * host -- IP address of our service
+# * type -- "server" or "http"
-    # * port -- port of our service
+# * host -- IP address of our service
-    # * keys -- file with LeaseSet of address in i2p
+# * port -- port of our service
-    # optional parameters (may be omitted)
+# * keys -- file with LeaseSet of address in i2p
-    # * inport -- optional, I2P service port, if unset - the same as 'port'
+# optional parameters (may be omitted)
-    # * accesslist -- comma-separated list of I2P addresses, allowed to connect
+# * inport -- optional, I2P service port, if unset - the same as 'port'
-    #    every address is b32 without '.b32.i2p' part
+# * accesslist -- comma-separated list of I2P addresses, allowed to connect
-    [LOCALSITE]
+#    every address is b32 without '.b32.i2p' part
-    type = http
+[LOCALSITE]
-    host = 127.0.0.1
+type = http
-    port = 80
+host = 127.0.0.1
-    keys = site-keys.dat
+port = 80
-    #
+keys = site-keys.dat
-    [IRC-SERVER]
+#
-    type = server
+[IRC-SERVER]
-    host = 127.0.0.1
+type = server
-    port = 6667
+host = 127.0.0.1
-    keys = irc.dat
+port = 6667
-
+keys = irc.dat
+```