'\" t
.\"     Title: meek-server
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 09/14/2021
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "MEEK\-SERVER" "1" "09/14/2021" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
meek-server \- The meek server transport plugin
.SH "SYNOPSIS"
.sp
\fBmeek\-server\fR \fB\-\-acme\-hostnames\fR=\fIHOSTNAME\fR [\fIOPTIONS\fR]
.SH "DESCRIPTION"
.sp
meek\-server is a transport plugin for Tor that encodes a stream as a sequence of HTTP requests and responses\&.
.sp
You will need to configure TLS certificates\&. There are two ways to set up certificates:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-acme\-hostnames\fR=\fIHOSTNAME\fR
(with optional
\fB\-\-acme\-email\fR=\fIEMAIL\fR) will automatically get certificates for
\fIHOSTNAME\fR
using Let\(cqs Encrypt\&. When you use this option, meek\-server will need to be able to listen on port 80\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fB\-\-cert\fR=\fIFILENAME\fR
and
\fB\-\-key\fR=\fIFILENAME\fR
allow use to use your own externally acquired certificate\&.
.RE
.sp
Configuration for meek\-server usually appears in a torrc file\&. Here is a sample configuration using automatic Let\(cqs Encrypt certificates:
.sp
.if n \{\
.RS 4
.\}
.nf
ExtORPort auto
ServerTransportListenAddr meek 0\&.0\&.0\&.0:443
ServerTransportPlugin meek exec \&./meek\-server \-\-acme\-hostnames meek\-server\&.example \-\-log meek\-server\&.log
.fi
.if n \{\
.RE
.\}
.sp
Here is a sample configuration using externally acquired certificates:
.sp
.if n \{\
.RS 4
.\}
.nf
ExtORPort auto
ServerTransportListenAddr meek 0\&.0\&.0\&.0:8443
ServerTransportPlugin meek exec \&./meek\-server 8443 \-\-cert cert\&.pem \-\-key key\&.pem \-\-log meek\-server\&.log
.fi
.if n \{\
.RE
.\}
.sp
To listen on ports 80 and 443 without needed to run as root, on Linux, you can use the setcap program, part of libcap2:
.sp
.if n \{\
.RS 4
.\}
.nf
setcap \*(Aqcap_net_bind_service=+ep\*(Aq /usr/local/bin/meek\-server
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.PP
\fB\-\-acme\-email\fR=\fIEMAIL\fR
.RS 4
Optional email address to register for Let\(cqs Encrypt notifications when using
\fB\-\-acme\-hostnames\fR\&.
.RE
.PP
\fB\-\-acme\-hostnames\fR=\fIHOSTNAME\fR[,\fIHOSTNAME\fR]\&...
.RS 4
Comma\-separated list of hostnames to honor when getting automatic certificates from Let\(cqs Encrypt\&. meek\-server will open a special listener on port 80 in order to handle ACME messages; this listener is separate from the one specified by
ServerTransportListenAddr\&. The certificates will be cached in the pt_state/meek\-certificate\-cache directory inside tor state directory\&.
.RE
.PP
\fB\-\-cert\fR=\fIFILENAME\fR
.RS 4
Name of a PEM\-encoded TLS certificate file\&. Required unless
\fB\-\-acme\-hostnames\fR
or
\fB\-\-disable\-tls\fR
is used\&.
.RE
.PP
\fB\-\-disable\-tls\fR
.RS 4
Use plain HTTP rather than HTTPS\&. This option is only for testing purposes\&. Don\(cqt use it in production\&.
.RE
.PP
\fB\-\-key\fR=\fIFILENAME\fR
.RS 4
Name of a PEM\-encoded TLS private key file\&. Required unless
\fB\-\-acme\-hostnames\fR
or
\fB\-\-disable\-tls\fR
is used\&.
.RE
.PP
\fB\-\-log\fR=\fIFILENAME\fR
.RS 4
Name of a file to write log messages to (default stderr)\&.
.RE
.PP
\fB\-\-port\fR=\fIPORT\fR
.RS 4
Port to listen on\&. Overrides the
TOR_PT_SERVER_BINDADDR
environment variable set by tor\&. In most cases you should set the
\fBServerTransportListenAddr\fR
option in torrc, rather than use the
\fB\-\-port\fR
option\&.
.RE
.PP
\fB\-h\fR, \fB\-\-help\fR
.RS 4
Display a help message and exit\&.
.RE
.SH "SEE ALSO"
.sp
\fBhttps://trac\&.torproject\&.org/projects/tor/wiki/doc/meek\fR
.SH "BUGS"
.sp
Please report at \fBhttps://trac\&.torproject\&.org/projects/tor\fR\&.