From c32fb66558d393a8c8145f7b9bd0aa91e74d5208 Mon Sep 17 00:00:00 2001 From: idk Date: Tue, 4 Dec 2018 10:30:14 -0500 Subject: [PATCH] new docs --- Makefile | 2 +- README.md | 15 +- README.md.asc | 31 ++-- USAGE.md | 263 ------------------------------ EMBEDDING.md => docs/EMBEDDING.md | 12 +- docs/USAGE.md | 2 + manager/manager.go | 1 - 7 files changed, 34 insertions(+), 292 deletions(-) delete mode 100644 USAGE.md rename EMBEDDING.md => docs/EMBEDDING.md (89%) diff --git a/Makefile b/Makefile index 8d5c2ec..a076d5c 100644 --- a/Makefile +++ b/Makefile @@ -191,7 +191,7 @@ example-config: cat etc/samcatd/tunnels.ini >> USAGE.md @echo '```' >> USAGE.md @echo "" >> USAGE.md - cp USAGE.md docs/USAGE.md + mv USAGE.md docs/USAGE.md docker-build: diff --git a/README.md b/README.md index 7185e54..619142e 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ and it will be in the folder ./bin/ [![Build Status](https://travis-ci.org/eyedeekay/sam-forwarder.svg?branch=master)](https://travis-ci.org/eyedeekay/sam-forwarder) -## [usage/configuration](USAGE.md) +## [usage/configuration](docs/USAGE.md) ## binaries @@ -36,12 +36,13 @@ Current limitations: ==================== I need to document it better. -[Besides fixing up the comments, this should help for now.](USAGE.md). I also -need to control output verbosity better. +[Besides fixing up the comments, this should help for now.](docs/USAGE.md). I +also need to control output verbosity better. I need samcatd to accept a configuration folder identical to /etc/i2pd/tunnels.conf.d, since part of the point of this is to be compatible -with i2pd's tunnels configuration. +with i2pd's tunnels configuration. Once this is done, I'll resume turning it +into a .deb package. It doesn't encrypt the .i2pkeys file by default, so if someone can steal them, then they can use them to construct tunnels to impersonate you. Experimental @@ -51,9 +52,9 @@ to determine how to go about managing these keys. TCP and UDP are both working now. Additional functionality might be added by adding other kinds of protocols overtop the TCP and UDP tunnels as a primitive. -A very basic UDP based VPN will be added soon. Obviously these won't be i2pd -compatible. Not sure what to do about that, except maybe make a "convert" tool -that will cull samcatd-specific options. +There's a very basic UDP-based VPN available in samcatd by configuration-file +only for now. Also it requires root. Probably need to split the VPN part into +it's own application. I've only enabled the use of a subset of the i2cp and tunnel configuration options, the ones I use the most and for no other real reason assume other diff --git a/README.md.asc b/README.md.asc index d343d1f..0599610 100644 --- a/README.md.asc +++ b/README.md.asc @@ -25,7 +25,7 @@ and it will be in the folder ./bin/ [![Build Status](https://travis-ci.org/eyedeekay/sam-forwarder.svg?branch=master)](https://travis-ci.org/eyedeekay/sam-forwarder) -## [usage/configuration](USAGE.md) +## [usage/configuration](docs/USAGE.md) ## binaries @@ -39,12 +39,13 @@ Current limitations: ==================== I need to document it better. -[Besides fixing up the comments, this should help for now.](USAGE.md). I also -need to control output verbosity better. +[Besides fixing up the comments, this should help for now.](docs/USAGE.md). I +also need to control output verbosity better. I need samcatd to accept a configuration folder identical to /etc/i2pd/tunnels.conf.d, since part of the point of this is to be compatible -with i2pd's tunnels configuration. +with i2pd's tunnels configuration. Once this is done, I'll resume turning it +into a .deb package. It doesn't encrypt the .i2pkeys file by default, so if someone can steal them, then they can use them to construct tunnels to impersonate you. Experimental @@ -54,9 +55,9 @@ to determine how to go about managing these keys. TCP and UDP are both working now. Additional functionality might be added by adding other kinds of protocols overtop the TCP and UDP tunnels as a primitive. -A very basic UDP based VPN will be added soon. Obviously these won't be i2pd -compatible. Not sure what to do about that, except maybe make a "convert" tool -that will cull samcatd-specific options. +There's a very basic UDP-based VPN available in samcatd by configuration-file +only for now. Also it requires root. Probably need to split the VPN part into +it's own application. I've only enabled the use of a subset of the i2cp and tunnel configuration options, the ones I use the most and for no other real reason assume other @@ -102,12 +103,12 @@ Donate BTC:159M8MEUwhTzE9RXmcZxtigKaEjgfwRbHt -----BEGIN PGP SIGNATURE----- -iQEzBAEBCAAdFiEEcNIGBzi++AUjrK/311wDs5teFOEFAlwFrTAACgkQ11wDs5te -FOGInAf+JmBR3SladLuDAnd/ADI0Dj8WfZDUDTvSZYoeQaom94upysxYWWmhtvQu -+ewNGshdLp/KI60m3L8YhcTSW+XuNyE/Ibb1jgpCIgyF6ARixD+xmOXjTHNZgeeh -juIe14SXr9LO4XzsMio8yS951JJYMWeD6tGIWmM8qYViKjmPDsfF+2v3jYAqyyqR -a+HIBHtphgSVGd7BtaJS6DS2OFGKNzmNqaxWbQRQbUQUSbf0wTFA+YmLQ2s4p+YG -saPt2bOmzS0uRivrtXHETuOF57yvI2QHMS/y1CZJ60RAhIlyqUm64CoGGfbRGhJJ -SaPEQ8tYHBjUHpHlkSTlFsadGFLooA== -=rxe6 +iQEzBAEBCAAdFiEEcNIGBzi++AUjrK/311wDs5teFOEFAlwGnYMACgkQ11wDs5te +FOHf6Qf/VLksUuSZny+fJn9hOPcBsyueNq38AFLLJbK7v6F7Whl2HfopfS+i+lKg +PzZWBGB6j7niPPF18VHZmpDhUx7je6nR80JY69hsiLUXr+hJHY02uYo/B0T2LnW+ +FAx3Gh/rSO0YJ91sK46r2BnDcZlotxTW8dj1jqHABAQI85b9apq+/bujRu5YE5ls +3Wfil78XvpC7hzX8MoyNCYNNho9U5p7LtdKw9nNgEN5YTCZ1RAO2zDROVl2W89BN +P3Pz2n1vTvMC8gyaFPTuM1ab57uckbXZl3ZKsBBVuwrnjaUUIwlhdt1i5VSNI3Mr +QHgfncFuBOJhqCI/4m/5bJPJMiUtbg== +=/lJZ -----END PGP SIGNATURE----- diff --git a/USAGE.md b/USAGE.md deleted file mode 100644 index 758fec6..0000000 --- a/USAGE.md +++ /dev/null @@ -1,263 +0,0 @@ -ephsite - Easy forwarding of local services to i2p -================================================== - -ephsite is a forwarding proxy designed to configure a tunnel for use -with i2p. It can be used to easily forward a local service to the -i2p network using i2p's SAM API instead of the tunnel interface. - -usage: ------- - -``` -Usage of ./bin/ephsite: - -access string - Type of access list to use, can be "whitelist" "blacklist" or "none". (default "none") - -accesslist value - Specify an access list member(can be used multiple times) - -client - Client proxy mode(true or false) - -close - Close tunnel idle(true or false) - -closetime int - Reduce tunnel quantity after X (milliseconds) (default 600000) - -dest string - Destination for client tunnels. Ignored for service tunnels. (default "none") - -dir string - Directory to save tunnel configuration file in. - -encryptlease - Use an encrypted leaseset(true or false) (default true) - -gzip - Uze gzip(true or false) - -headers - Inject X-I2P-DEST headers - -host string - Target host(Host of service to forward to i2p) (default "127.0.0.1") - -inback int - Set inbound tunnel backup quantity(0 to 5) (default 4) - -incount int - Set inbound tunnel quantity(0 to 15) (default 6) - -ini string - Use an ini file for configuration(config file options override passed arguments for now.) (default "none") - -inlen int - Set inbound tunnel length(0 to 7) (default 3) - -invar int - Set inbound tunnel length variance(-7 to 7) - -lsk string - path to saved encrypted leaseset keys (default "none") - -name string - Tunnel name, this must be unique but can be anything. (default "forwarder") - -outback int - Set outbound tunnel backup quantity(0 to 5) (default 4) - -outcount int - Set outbound tunnel quantity(0 to 15) (default 6) - -outlen int - Set outbound tunnel length(0 to 7) (default 3) - -outvar int - Set outbound tunnel length variance(-7 to 7) - -port string - Target port(Port of service to forward to i2p) (default "8081") - -reduce - Reduce tunnel quantity when idle(true or false) - -reducecount int - Reduce idle tunnel quantity to X (0 to 5) (default 3) - -reducetime int - Reduce tunnel quantity after X (milliseconds) (default 600000) - -samhost string - SAM host (default "127.0.0.1") - -samport string - SAM port (default "7656") - -save - Use saved file and persist tunnel(If false, tunnel will not persist after program is stopped. - -tlsport string - (Currently inoperative. Target TLS port(HTTPS Port of service to forward to i2p) - -udp - UDP mode(true or false) - -zeroin - Allow zero-hop, non-anonymous tunnels in(true or false) - -zeroout - Allow zero-hop, non-anonymous tunnels out(true or false) -``` - -samcatd - Router-independent tunnel management for i2p -========================================================= - -samcatd is a daemon which runs a group of forwarding proxies to -provide services over i2p independent of the router. It also serves -as a generalized i2p networking utility for power-users. It's -intended to be a Swiss-army knife for the SAM API. - -usage: ------- - -``` -flag needs an argument: -h -Usage of ./bin/samcatd: - -a string - Type of access list to use, can be "whitelist" "blacklist" or "none". (default "none") - -accesslist value - Specify an access list member(can be used multiple times) - -c Client proxy mode(true or false) - -cr string - Encrypt/decrypt the key files with a passfile - -css string - custom CSS for web interface (default "css/styles.css") - -ct int - Reduce tunnel quantity after X (milliseconds) (default 600000) - -d string - Directory to save tunnel configuration file in. - -de string - Destination to connect client's to by default. - -f string - Use an ini file for configuration(config file options override passed arguments for now.) (default "none") - -h string - Target host(Host of service to forward to i2p) (default "127.0.0.1") - -i string - Destination for client tunnels. Ignored for service tunnels. (default "none") - -ib int - Set inbound tunnel backup quantity(0 to 5) (default 2) - -ih - Inject X-I2P-DEST headers - -il int - Set inbound tunnel length(0 to 7) (default 3) - -iq int - Set inbound tunnel quantity(0 to 15) (default 6) - -iv int - Set inbound tunnel length variance(-7 to 7) - -js string - custom JS for web interface (default "js/scripts.js") - -k string - key for encrypted leaseset (default "none") - -l Use an encrypted leaseset(true or false) (default true) - -n string - Tunnel name, this must be unique but can be anything. (default "forwarder") - -ob int - Set outbound tunnel backup quantity(0 to 5) (default 2) - -ol int - Set outbound tunnel length(0 to 7) (default 3) - -oq int - Set outbound tunnel quantity(0 to 15) (default 6) - -ov int - Set outbound tunnel length variance(-7 to 7) - -p string - Target port(Port of service to forward to i2p) (default "8081") - -pk string - private key for encrypted leaseset (default "none") - -psk string - private signing key for encrypted leaseset (default "none") - -r Reduce tunnel quantity when idle(true or false) - -rq int - Reduce idle tunnel quantity to X (0 to 5) (default 3) - -rt int - Reduce tunnel quantity after X (milliseconds) (default 600000) - -s Start a tunnel with the passed parameters(Otherwise, they will be treated as default values.) - -sh string - SAM host (default "127.0.0.1") - -sp string - SAM port (default "7656") - -t Use saved file and persist tunnel(If false, tunnel will not persist after program is stopped. - -tls string - (Currently inoperative. Target TLS port(HTTPS Port of service to forward to i2p) - -u UDP mode(true or false) - -w Start web administration interface - -wp string - Web port (default "7957") - -x Close tunnel idle(true or false) - -z Uze gzip(true or false) - -zi - Allow zero-hop, non-anonymous tunnels in(true or false) - -zo - Allow zero-hop, non-anonymous tunnels out(true or false) -``` - -managing samcatd save-encryption keys -===================================== - -In order to keep from saving the .i2pkeys files in plaintext format, samcatd -can optionally generate a key and encrypt the .i2pkeys files securely. Of -course, to fully benefit from this arrangement, you need to move those keys -away from the machine where the tunnel keys(the .i2pkeys file) are located, -or protect them in some other way(sandboxing, etc). If you want to use -encrypted .i2pkeys files, you can specify a key file to use with the -cr -option on the terminal or with keyfile option in the .ini file. - -example config - valid for both ephsite and samcat -================================================== -Options are still being added, pretty much as fast as I can put them -in. For up-to-the-minute options, see [the checklist](config/CHECKLIST.md) - -(**ephsite** will only use top-level options, but they can be labeled or -unlabeled) - -(**samcatd** treats the first set of options it sees as the default, and -does not start tunnels based on unlabeled options unless passed the --s flag.) - -``` ini - -## Defaults, these are only invoked with the -start option or if labeled tunnels -## are not present(samcatd instructions). **THESE** are the correct config files -## to use as defaults, and not the ones in ../sam-forwarder/tunnels.ini, which -## are used for testing settings availability only. - -inbound.length = 3 -outbound.length = 3 -inbound.lengthVariance = 0 -outbound.lengthVariance = 0 -inbound.backupQuantity = 3 -outbound.backupQuantity = 3 -inbound.quantity = 5 -outbound.quantity = 5 -inbound.allowZeroHop = false -outbound.allowZeroHop = false -i2cp.encryptLeaseSet = false -gzip = true -i2cp.reduceOnIdle = true -i2cp.reduceIdleTime = 3000000 -i2cp.reduceQuantity = 2 -i2cp.enableWhiteList = false -i2cp.enableBlackList = false -keyfile = "/usr/share/samcatd/samcatd" - -#[sam-forwarder] -#type = server -#host = 127.0.0.1 -#port = 8081 -#inbound.length = 3 -#outbound.length = 3 -#keys = forwarder - -[sam-forwarder-two] -type = client -host = 127.0.0.1 -port = 8082 -inbound.length = 3 -outbound.length = 3 -destination = i2p-projekt.i2p -keys = forwarder-two - -#[sam-forwarder-three] -#type = udpclient -#host = 127.0.0.1 -#port = 8083 -#inbound.length = 3 -#outbound.length = 3 -#destination = i2p-projekt.i2p -#keys = forwarder-three - -#[sam-forwarder-four] -#type = udpserver -#host = 127.0.0.1 -#port = 8084 -#inbound.length = 6 -#outbound.length = 3 -#keys = forwarder-four - -#[sam-forwarder-five] -#type = http -#host = 127.0.0.1 -#port = 8085 -#inbound.length = 3 -#outbound.length = 3 -#keys = forwarder-five -``` - diff --git a/EMBEDDING.md b/docs/EMBEDDING.md similarity index 89% rename from EMBEDDING.md rename to docs/EMBEDDING.md index 0ad7a16..d11da9d 100644 --- a/EMBEDDING.md +++ b/docs/EMBEDDING.md @@ -7,11 +7,11 @@ with this process, the samforwarder/config/ file has a bunch of helper functions and a class for parsing configuration files directly. You can import it, add a few flags(or however you configure your service) and fire off the forwarder as a goroutne, all you have to do is configure it to forward the port -used by your service. This makes it extremely easy to do, but in my opinion, it -should only be used in this way for applications that would already be safe to -host as services in i2p or other overlay networks. That means avoiding the risk -of out-of-band communication accidentally, such as by making the server retrieve -a resource from a clearnet service. +used by your service. This makes it extremely easy to do, but it should only be +used in this way for applications that would already be safe to host as services +in i2p or other overlay networks. In particular, it should only be used for +applications that don't require extensive login information and do not leak +information at the application layer. So without further ado, a blatant copy-paste of information that shouldn't have been in the README.md. @@ -74,3 +74,5 @@ func main() { func main() { ``` [This tiny file server taken from here and used for this example](https://gist.github.com/paulmach/7271283) + +## Integrating your Go web application with i2p using sam-forwarder diff --git a/docs/USAGE.md b/docs/USAGE.md index 758fec6..c3a52c5 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -97,6 +97,8 @@ Usage of ./bin/samcatd: -accesslist value Specify an access list member(can be used multiple times) -c Client proxy mode(true or false) + -conv string + Display the base32 and base64 values of a specified .i2pkeys file -cr string Encrypt/decrypt the key files with a passfile -css string diff --git a/manager/manager.go b/manager/manager.go index b1d6e82..922a72c 100644 --- a/manager/manager.go +++ b/manager/manager.go @@ -308,7 +308,6 @@ func NewSAMManagerFromOptions(opts ...func(*SAMManager) error) (*SAMManager, err } else { return nil, fmt.Errorf(e.Error()) } - case "vpnserver": if f, e := samforwardervpn.NewSAMVPNForwarderFromConfig(s.FilePath, s.SamHost, s.SamPort); e == nil { log.Println("found default vpnserver")