idk/sam-forwarder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

new docs

Browse Source
This commit is contained in:
idk
2018-12-04 10:30:14 -05:00
parent addfd33936
commit c32fb66558
7 changed files with 34 additions and 292 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
Makefile
View File

@ -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:

15
README.md
View File

@ -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

31
README.md.asc
View File

@ -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-----

263
USAGE.md
View File

@ -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
```

12
EMBEDDING.md → docs/EMBEDDING.md
View File

@ -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

2
docs/USAGE.md
View File

@ -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

1
manager/manager.go
View File

@ -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")