.\" Manual page for openvpn.\" SH section heading.\" SS subsection heading.\" LP paragraph.\" IP indented paragraph.\" TP hanging labelopenvpn.TH openvpn 8 "20 October 2002".SH NAMEopenvpn \- secure IP tunnel daemon..SH SYNOPSIS.LP.nh.in +4.ti -4.B openvpn[\ \fB\-\-help\fR\ ].in -4.ti +4.hy.nh.in +4.ti -4.B openvpn[\ \fB\-\-config\fR\ \fIfile\fR\ ].in -4.ti +4.hy.nh.in +4.ti -4.B openvpn[\ \fB\-\-genkey\fR\ ][\ \fB\-\-secret\fR\ \fIfile\fR\ ].in -4.ti +4.hy.nh.in +4.ti -4.B openvpn[\ \fB\-\-mktun\fR\ ][\ \fB\-\-rmtun\fR\ ][\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\fR\ ][\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ][\ \fB\-\-dev\-node\fR\ \fInode\fR\ ].in -4.ti +4.hy.nh.in +4.ti -4.B openvpn[\ \fB\-\-test\-crypto\fR\ ][\ \fB\-\-secret\fR\ \fIfile\fR\ ][\ \fB\-\-auth\fR\ \fIalg\fR\ ][\ \fB\-\-cipher\fR\ \fIalg\fR\ ][\ \fB\-\-keysize\fR\ \fIn\fR\ ][\ \fB\-\-no\-replay\fR\ ][\ \fB\-\-no\-iv\fR\ ].in -4.ti +4.hy.nh.in +4.ti -4.B openvpn[\ \fB\-\-config\fR\ \fIfile\fR\ ][\ \fB\-\-local\fR\ \fIhost\fR\ ][\ \fB\-\-remote\fR\ \fIhost\fR\ ][\ \fB\-\-resolv\-retry\fR\ \fIn\fR\ ][\ \fB\-\-float\fR\ ][\ \fB\-\-ipchange\fR\ \fIcmd\fR\ ][\ \fB\-\-port\fR\ \fIport\fR\ ][\ \fB\-\-lport\fR\ \fIport\fR\ ][\ \fB\-\-rport\fR\ \fIport\fR\ ][\ \fB\-\-nobind\fR\ ][\ \fB\-\-dev\fR\ \fItunX\ |\ tapX\ |\ null\fR\ ][\ \fB\-\-tun\-ipv6\fR\ ][\ \fB\-\-dev\-type\fR\ \fIdevice\-type\fR\ ][\ \fB\-\-dev\-node\fR\ \fInode\fR\ ][\ \fB\-\-ifconfig\fR\ \fIl\ r\fR\ ][\ \fB\-\-udp\-mtu\fR\ \fIn\fR\ ][\ \fB\-\-tun\-mtu\fR\ \fIn\fR\ ][\ \fB\-\-shaper\fR\ \fIn\fR\ ][\ \fB\-\-inactive\fR\ \fIn\fR\ ][\ \fB\-\-ping\fR\ \fIn\fR\ ][\ \fB\-\-ping\-exit\fR\ \fIn\fR\ ][\ \fB\-\-ping\-restart\fR\ \fIn\fR\ ][\ \fB\-\-ping\-timer\-rem\fR\ ][\ \fB\-\-persist\-tun\fR\ ][\ \fB\-\-persist\-key\fR\ ][\ \fB\-\-persist\-local\-ip\fR\ ][\ \fB\-\-persist\-remote\-ip\fR\ ][\ \fB\-\-mlock\fR\ ][\ \fB\-\-up\fR\ \fIcmd\fR\ ][\ \fB\-\-down\fR\ \fIcmd\fR\ ][\ \fB\-\-user\fR\ \fIuser\fR\ ][\ \fB\-\-group\fR\ \fIgroup\fR\ ][\ \fB\-\-cd\fR\ \fIdir\fR\ ][\ \fB\-\-chroot\fR\ \fIdir\fR\ ][\ \fB\-\-daemon\fR\ ][\ \fB\-\-inetd\fR\ ][\ \fB\-\-writepid\fR\ \fIfile\fR\ ][\ \fB\-\-nice\fR\ \fIn\fR\ ][\ \fB\-\-nice\-work\fR\ \fIn\fR\ ][\ \fB\-\-verb\fR\ \fIn\fR\ ][\ \fB\-\-mute\fR\ \fIn\fR\ ][\ \fB\-\-gremlin\fR\ ][\ \fB\-\-comp\-lzo\fR\ ][\ \fB\-\-comp\-noadapt\fR\ ][\ \fB\-\-secret\fR\ \fIfile\fR\ ][\ \fB\-\-auth\fR\ \fIalg\fR\ ][\ \fB\-\-cipher\fR\ \fIalg\fR\ ][\ \fB\-\-keysize\fR\ \fIn\fR\ ][\ \fB\-\-no\-replay\fR\ ][\ \fB\-\-no\-iv\fR\ ][\ \fB\-\-tls\-server\fR\ ][\ \fB\-\-tls\-client\fR\ ][\ \fB\-\-ca\fR\ \fIfile\fR\ ][\ \fB\-\-dh\fR\ \fIfile\fR\ ][\ \fB\-\-cert\fR\ \fIfile\fR\ ][\ \fB\-\-key\fR\ \fIfile\fR\ ][\ \fB\-\-tls\-cipher\fR\ \fIl\fR\ ][\ \fB\-\-tls\-timeout\fR\ \fIn\fR\ ][\ \fB\-\-reneg\-bytes\fR\ \fIn\fR\ ][\ \fB\-\-reneg\-pkts\fR\ \fIn\fR\ ][\ \fB\-\-reneg\-sec\fR\ \fIn\fR\ ][\ \fB\-\-hand\-window\fR\ \fIn\fR\ ][\ \fB\-\-tran\-window\fR\ \fIn\fR\ ][\ \fB\-\-single\-session\fR\ ][\ \fB\-\-tls\-auth\fR\ \fIf\fR\ ][\ \fB\-\-askpass\fR\ ][\ \fB\-\-tls\-verify\fR\ \fIcmd\fR\ ][\ \fB\-\-disable\-occ\fR\ ].in -4.ti +4.hy.SH DESCRIPTION.LPOpenVPN is a robust and highly configurable secure tunneling daemon whichtunnels IP networks over UDP.  OpenVPN provides a comprehensive suite ofsecurity features including conventional encryption, public key encryption,dynamic key exchange, perfect forward security,and the choice of any cipher, key size, or HMAC digest (for packetauthentication) offered by the.B OpenSSLlibrary.OpenVPN supportsconventional encryptionusing a pre-shared secret key.B (Static Key mode)orpublic key encryption.B (TLS-mode)using client & server certificates.OpenVPN alsosupports non-encrypted UDP tunnels.  When used in public keyencryption mode, OpenVPN utilizes the.B TLSprotocol for peer authentication and dynamic key exchange.TLS is the latest evolution of the SSL family of protocols developedoriginally by Netscape for their first secure web browser.TLS and its SSL predecessorshave seen widespread usage on the web for many yearsand have been extensively analyzed for weaknesses.  As such,I believe TLS is an excellent choice for the authentication and key exchangemechanism of a VPN product.In TLS mode, OpenVPN uses a dual control-channel/data-channel mode of operation.The control channel runs a TLS session which is used to exchange randomlygenerated cipher and HMAC keys.Those keys are then used to encrypt and authenticate the data channel.Both channels are multiplexedover a single UDP port.  A reliability layer is placed over the control channelsince TLS expects a reliable connection.  The data channel is passed unmediatedover the UDP channel since the higher level protocols running over the tunnel(such as TCP)will expect such behaviour.  The control channel will trigger a new keyexchange handshake periodically, according to user-specified parameters.OpenVPN's key exchange protocol has been designed for both securityand resilience to unreliable network conditions.  The protocolhas been rigorously stress-tested in situations that simulate highly unreliablenetworks which drop packets, suffer intermittent losses of connectivity,and even corrupt packet data.  No version of OpenVPN is released unlessit passes this test suite(see the.B --gremlin option below).OpenVPN is designed to work with the.B tun/tap driverwhich supports both IP and Ethernettunneling.  OpenVPN supports both dynamic and persistent tun/tap tunnels.OpenVPN can construct multiple tunnels to or from the same peer andwill peacefully co-exist with other applications which construct tun/tap tunnels.OpenVPN supports building multiple tunnels between the same two peers, whereeach tunnel has a different maximum bandwidth (see the.B --shaperoption below).OpenVPN is designed to work well on systems which have dynamically assigned IPaddresses such as dial-in or DHCP users.  OpenVPN has no problem remaining in synceven if.I bothpeers possess dynamic IP addresses, as long as they don't change their IP addressessimultaneously.OpenVPN is primarily a peer-to-peer application though it supports someclient/server modes such as the ability to designate a peer aseither a TLS server or client, or the ability to instantiate an OpenVPN peer withoutan explicit remote peer address.OpenVPN never uses more than a single UDP port to communicate with its peer.  OpenVPNdoesn't use the.B GREprotocol which can be a benefit for users running on networks thatdiscriminate against VPN users by blocking the GRE protocol.OpenVPN is highly efficient while giving users flexibility in choosingtradeoffs between efficiency and security.  All security optionswhich add packet overhead can be enabled or disabled withcommand line options.OpenVPN's build system is based on.B automakeand.B autoconfand offersseveral build options.  It can be built standalone, in whichcase it will only offer non-encrypted UDP tunnels; it can be builtwith the.B LZOreal-time compression library; it can be built with theOpenSSL crypto library which will give support for static private key encryption;it can be built with the OpenSSL SSL library which will give full supportfor certificates and TLS-based dynamic key exchange; and it can be builtwith pthread support for improved latency in SSL/TLS mode.  For more information, consultthe.B INSTALLfile included in the OpenVPN distribution.OpenVPN aims to offer many of the key features of IPSec butwith a very lightweight footprint..SH OPTIONS.TP.B --helpShow options..TP.B --config fileLoad additional config options from.B filewhere each line corresponds to one command line option,but with the leading '--' removed.Double quotation characters ("") can be usedto enclose single parameters containing whitespace,and "#" or ";" characters can be used to denote comments.Configuration files can be nested.For examples of configuration files,see the OpenVPN HOWTO at.I http://openvpn.sourceforge.net/howto.htmlHere is an example configuration file:.RS.ft 3.nf.sp## Sample OpenVPN configuration file for# using a pre-shared static key.## '#' or ';' may be used to delimit comments.# Use a dynamic tun device.dev tun# Our remote peerremote mypeer.mydomain# 10.1.0.1 is our local VPN endpoint# 10.1.0.2 is our remote VPN endpointifconfig 10.1.0.1 10.1.0.2# Our pre-shared static keysecret static.key.ft.LP.RE.fi.SS Tunnel Options:It should be noted that OpenVPN is a peer-to-peer application.  Each peer establishesa symmetrical UDP link with its partner.  If an OpenVPN session is started withoutan explicitly specified remote peer, OpenVPN willwait until it receives an authenticatedpacket from any IP address, in which case it will take this address as its peer.One of the ramifications of this behaviour is that eitherOpenVPN peer can be halted and restarted, and link will immediately resume.OpenVPN also provides a session-usurp feature:once a new session is authenticated it willusurp an old session.  This is useful for dial-in users.If your modem disconnects, and youmust reconnect to your ISP from a different IP address,you will immediately be able to reconnectto your remote OpenVPN peer and take control of the session.An OpenVPN peer will not ignore an authenticated connection request,even if it is busy trying to communicate withan old IP address that just got disconnected.  There is one exceptionto this behavior: the.B --single-sessionoption will disable the session-usurp feature in TLS mode.  The optiondoes not apply in static-key mode, as it is a stateless protocol withoutany notion of a session.An OpenVPN peer will try to stay connected indefinitely, even under conditions ofhigh network error frequency, until it receives a SIGINT or SIGTERM signal,or a time-out condition.A major design goal of OpenVPN is that it should be as responsive, in terms of both normaloperations and error recovery, as the underlying IP layer that it is tunneling over.That means that if the IP layer goes down for 5 minutes, when it comes back up,tunnel traffic will immediately resume even if the outage interfered witha dynamic key exchange which was scheduled during that time.Because OpenVPN runs in a single-process, single-thread mode, and exclusively usesnon-blocked I/O, it is fairly immune to the problem of hung or unresponsive processes.Another ramification of being a peer-to-peer application isthat OpenVPN will not dynamicallyfork to accept new clients. If you have three clients who need to securely connect to a machine,you should run 3 instantiations of OpenVPN on that machine,each on a different UDP portnumber.  This has certain advantages, among them being theindependence of each OpenVPN session.If you need to bring one session down it won'tinterfere with the others.  If you have tensor hundreds of clients who want to connect to asecure network, then you may want to considera more scalable solution such as IPSec.  OpenVPN is designed forsmall networks but withstrong security requirements.  That being said however,there's no reason why OpenVPN couldn'tscale to many users with the right underlying administration infrastructure..TP.B --local hostLocal host name or IP address.If specified, OpenVPN will bind to this address only.If unspecified, OpenVPN will bind to all interfaces..TP.B --remote hostRemote host name or IP address.  If unspecified, OpenVPN will listenfor packets from any IP address, but will not act on those packets unlessthey pass all authentication tests.  This requirement for authenticationis binding on all potential peers, even those from known and supposedlytrusted IP addresses (it is very easy to forge a source IP address ona UDP packet)..TP.B --resolv-retry nIf hostname resolve fails for.B --localor.B --remote,retry resolve for.B nseconds before failing (disabled by default)..TP.B --floatAllow remote peer to change its IP address and/or port number, such as due toDHCP (this is the default if.B --remoteis not used)..B --floatwhen specified with.B --remoteallows an OpenVPN session to initially connect to a peerat a known address, however if packets arrive from a newaddress and pass all authentication tests, the new addresswill take control of the session.  This is useful whenyou are connecting to a peer which holds a dynamic addresssuch as a dial-in user or DHCP client.Essentially,.B --floattells OpenVPN to accept authenticated packetsfrom any address, not only the address which was specified in the.B --remoteoption..TP.B --ipchange cmdExecute shell command.B cmdwhen our remote ip-address is initially authenticated orchanges.Execute as: