commit dd9074b389e8d187eff62bc42e968d0922fa1478 Author: David Fifield <david@bamsoftware.com> Date: Wed May 7 21:37:07 2014 -0700 Man pages for meek-client and meek-server. https://trac.torproject.org/projects/tor/ticket/11580 --- doc/Makefile | 11 +++++++ doc/meek-client.1.txt | 81 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/meek-server.1.txt | 64 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 156 insertions(+) diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..967d944 --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,11 @@ +MAN = meek-client.1 meek-server.1 + +all: $(MAN) + +%.1: %.1.txt + a2x --no-xmllint --xsltproc-opts "--stringparam man.th.title.max.length 11" -d manpage -f manpage $< + +clean: + rm -f $(MAN) + +.PHONY: all clean diff --git a/doc/meek-client.1.txt b/doc/meek-client.1.txt new file mode 100644 index 0000000..3f0e51f --- /dev/null +++ b/doc/meek-client.1.txt @@ -0,0 +1,81 @@ +// This file is asciidoc source code. +// To generate manpages, use the a2x command i.e. +// a2x --no-xmllint -d manpage -f manpage meek-client.1.txt +// see http://www.methods.co.nz/asciidoc/userguide.html#X1 +MEEK-CLIENT(1) +============== + +NAME +---- +meek-client - The meek client transport plugin + +SYNOPSIS +-------- +**meek-client** **--url**=__URL__ **--front**=__DOMAIN__ [__OPTIONS__] + +DESCRIPTION +----------- +meek-client is a transport plugin for Tor that encodes a stream as a +sequence of HTTP requests and responses. It is usually run with the +**--url** and **--front** options. The **--url** option controls what +URL requests are made to; the web server at that URL should be +configured to forward requests to a meek-server somewhere. The +**--front** option is for domain name camouflage: The domain name in the +URL is replaced by the front domain before the request is made, but the +Host header inside the HTTP request still points to the original domain. +The idea is to front through a domain that is not blocked to a domain +that is blocked. + +Configuration for meek-client usually appears in a torrc file. Most user +configuration can happen either through SOCKS args (i.e., args on a +Bridge line) or through command line options. SOCKS args take precedence +per-connection over command line options. For example, this +configuration using SOCKS args: +---- +Bridge meek 0.0.2.0:1 url=https://meek-reflect.appspot.com/ front=www.google.com +ClientTransportPlugin meek exec ./meek-client +---- +is the same as this one using command line options: +---- +Bridge meek 0.0.2.0:1 +ClientTransportPlugin meek exec ./meek-client --url=https://meek-reflect.appspot.com/ --front=www.google.com +---- +The advantage of SOCKS args is that multiple Bridge lines can have different +configurations. + +The **--helper** option prevents meek-client from doing any network +operations itself. Rather, it will send all requests through a browser +extension, which must be set up separately. + +OPTIONS +------- +**--front**=__DOMAIN__:: + Front domain name. The **front** SOCKS arg overrides the command + line. + +**--helper**=__ADDRESS__:: + Address of HTTP helper browser extension. For example, + **--helper 127.0.0.1:7000**. + +**--http-proxy**=__URL__:: + URL of HTTP proxy. If not given, the proxy URL may be taken from the + The **http-proxy** SOCKS arg overrides the command line. For + example, **--http-proxy=http://localhost:8787/**. + +**--log**=__FILENAME__:: + Name of a file to write log messages to (default stderr). + +**--url**=__URL__:: + URL to correspond with. The domain part of the URL may be modified + by **--front**. + +**-h**, **--help**:: + Display a help message and exit. + +SEE ALSO +-------- +**https://trac.torproject.org/projects/tor/wiki/doc/meek** + +BUGS +---- +Please report at **https://trac.torproject.org/projects/tor**. diff --git a/doc/meek-server.1.txt b/doc/meek-server.1.txt new file mode 100644 index 0000000..cb3b151 --- /dev/null +++ b/doc/meek-server.1.txt @@ -0,0 +1,64 @@ +// This file is asciidoc source code. +// To generate manpages, use the a2x command i.e. +// a2x --no-xmllint -d manpage -f manpage meek-client.1.txt +// see http://www.methods.co.nz/asciidoc/userguide.html#X1 +MEEK-SERVER(1) +============== + +NAME +---- +meek-server - The meek server transport plugin + +SYNOPSIS +-------- +**meek-server** **--cert**=__FILENAME__ **--key**=__FILENAME__ [__OPTIONS__] + +DESCRIPTION +----------- +meek-server is a transport plugin for Tor that encodes a stream as a +sequence of HTTP requests and responses. + +The server runs in HTTPS mode by default, and the **--cert** and +**--key** options are required. Use the **--disable-tls** option to run +with plain HTTP. + +Configuration for meek-server usually appears in a torrc file. Here is a +sample configuration using HTTPS: +---- +ServerTransportPlugin meek exec ./meek-server --port 8443 --cert cert.pem --key key.pem --log meek-server.log +---- +Here is a sample configuration using plain HTTP: +---- +ServerTransportPlugin meek exec ./meek-server --port 8080 --disable-tls --log meek-server.log +---- + +OPTIONS +------- +**--cert**=__FILENAME__:: + Name of a PEM-encoded TLS certificate file. Required unless + **--disable-tls** is used. + +**--disable-tls**: + Use plain HTTP rather than HTTPS. + +**--key**=__FILENAME__: + Name of a PEM-encoded TLS private key file. Required unless + **--disable-tls** is used. + +**--log**=__FILENAME__:: + Name of a file to write log messages to (default stderr). + +**--port**=__PORT__:: + Port to listen on. Overrides the TOR_PT_SERVER_BINDADDR environment + variable set by tor. + +**-h**, **--help**:: + Display a help message and exit. + +SEE ALSO +-------- +**https://trac.torproject.org/projects/tor/wiki/doc/meek** + +BUGS +---- +Please report at **https://trac.torproject.org/projects/tor**.