Reference Manual for OpenVPN 2.4 [WIP]

https://openvpn.net/community-resources/reference-manual-for-openvpn-2-4/

INTRODUCTION

OpenVPN это опен сорсный VPN демон от James Yonan. Так как OpenVPN пытается быть универсальным инструментом для VPN и предлагает большую гибкость, поэтому этот мануал содержит большое количество опций. Если ты новичок в VPN, то можешь захотеть пропустить многие разделы и перейти сразу к разделу с примерами, где ты сможешь увидеть как построить простой VPN через командную строку без необходимости конфигурировать какие-либо файлы

Также отметим что есть много документации и примеров на https://openvpn.net/

И если ты хочешь увидеть короткую верию этого мануала, смотри openvpn usage message который может быть получен запуском openvpn без каких-либо параметров

DESCRIPTION

OpenVPN это мощные и очень гибкий vpn-демон. OpenVPN поддерживает SSL/TLS, ethernet bridging, TCP или UDP туннелирование сквозь прокси или NATы, поддерживает динамические IP адреса и DHCP, масштабируется до сотен или тысяч пользователей и доступен для множества основных OS

OpenVPN плотно связан с библиотекой OpenSSL и получает оттуда много крипто функционала

OpenVPN поддерживает обычное шифрование используя pre-shared secret key (Static Key mode) или public key security (SSL/TLS mode) используя сертификаты клиента и сервера. OpenVPN также поддерживает нешифрованные TCP/UDP туннели

OpenVPN спроектирован чтобы работать с виртуальными сетевыми интерфейсами TUN/TAP которые присутствуют на множестве платформ

В целом, OpenVPN нацелен предложить множество ключевых функций IPSec, но с относительной легковесностью

OPTIONS

OpenVPN позволяет любой опции находиться как в команде запуска, так и в конфигурационном файле. Хотя все опции в командной строке предваряются двойным тире (--), этот префикс может быть опущен когда опция размещается в конфигурационном файле

• --help - Show options

• --config file - Загружает дополнительные конфигурационные опции из файла file, где каждая строка представляет одну опцию командной строки с опущенным --. Если --config file единственная опция для openvpn, то сама опция --config может быть опущена и команда запуска тогда будет выглядеть как openvpn file

  Отметим что конфигурационные файлы могут иметь вложенность до разумной глубины

  Символы двойных или одинарных кавычек (", ') могут быть использованы для окружения одиночного параметра содержащего пробел, а символы # или ; идущие первым символом строки определяют строку как комментарий

  Отметим что начиная с версии 2.0, OpenVPN обрабатывает backslash-based shell escaping для символов вне одиночных кавычек:

  \\       Maps to a single backslash character (\).
  \"       Pass a literal doublequote character ("), don't
           interpret it as enclosing a parameter.
  \[SPACE] Pass a literal space or tab character, don't
           interpret it as a parameter delimiter.
  

  Примеры конфигурационных файлов смотри в https://openvpn.net/community-resources/how-to/

  Ниже пример конфигурационного файла:

  #
  # 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 peer
  remote mypeer.mydomain
  
  # 10.1.0.1 is our local VPN endpoint
  # 10.1.0.2 is our remote VPN endpoint
  ifconfig 10.1.0.1 10.1.0.2
  
  # Our pre-shared static key
  secret static.key
  

Tunnel Options

• --mode m - Устанавливает основной режим OpenVPN. По умолчанию OpenVPN запускается в режиме point-to-point ("p2p"). Начиная с версии 2.0 введен новый режим ("server") который реализует multi-client server

• --local host - Локальное имя или IP адрес для прослушивания (bind). Если указано, то OpenVPN привяжется только к указанному адресу, если не указано, то OpenVPN будет прослушивать все интерфейсы

• --remote host [port] [proto] - Удаленный хост или IP адрес. На клиенте может быть указано множество опций --remote для отказоустойчивости, каждая указывает на отдельный OpenVPN сервер. Указание множества опций --remote для этой цели является частным случаем более общей функции connection-profile. См. ниже документацию <connection>. OpenVPN клиент будет пытаться подключиться к серверу на host:port в порядке указания опций --remote

  proto указывает протокол для подключения к remote и может быть "tcp" или "udp"

  Для насильного указания IPv4 или IPv6 можно добавить суффикс 4/6 к tcp/udp - udp4/udp6/tcp4/tcp6

  Клиент будет перемещаться на следующий хост из списка при ошибке подключения. Отметим что в любой момент времени один OpenVPN клиент может быть подключен только к одному OpenVPN серверу

  Так как UDP не имеет подключения, то ошибки подключения определяются опциями --ping и --ping-restart

  Отметим следующий corner case: Если ты используешь множество опций --remote, И ты убрал root привелегию на клиенте с помощью --user и/или --group, И клиент запущен на не-Windows OS, если клиенту нужно переключиться на следующий сервер и этот сервер пушит в ответ другие настройки TUN/TAP или маршруты, то клиенту может не хватить привелегий чтобы закрыть и переоткрыть TUN/TAP интерфейс. Это приведет к фатальной ошибке на клиенте

  Если опция --remote не указана, то OpenVPN будет принимать пакеты от всех IP адресов, но не будет реагировать на эти пакеты пока они не пройдут все тесты аутентификации. Это требование аутентификации накладывается на всех потенциальных пиров, даже для известных и предположительно доверенных IP адресов (очень просто подделать исходный IP адрес в UDP пакете)

  Когда используется режим TCP, --remote будет работать как фильтр, отвергая подключения от всех хостов которые не матчатся с host

  Если host это DNS имя которое резолвится в множество IP адресов, OpenVPN будет пробовать их в порядке в котором система выдала их (getaddrinfo()), так вопрос приоритизации и рандомизации закрывается системной библиотекой. Когда версия протокола не указана (с помощью префикса 4/6), OpenVPN будет пробовать и IPv4 и IPv6 адреса в порядке полученном от getaddrinfo()

• --remote-random-hostname - Предваряет рандомной строкой (6 bytes, 12 hex characters) хостнейм чтобы предотвратить DNS кэширование. Например, "foo.bar.gov" будет модифицирован в "<random-chars>.foo.bar.gov"

• <connection> - Описывает клиентский профиль подключения. Профиль это группа опций которая описывает как подключаться к выбранному OpenVPN серверу. Профили описываются в конфигурационном файле и каждый профиль окружается <connection> и </connection>. OpenVPN клиент будет последовательно пробовать профили пока успешно не подключится

• --remote-random - Может быть использован для начального перемешивания remote'ов
  Пример использования профилей:

  client
  dev tun
  
  <connection>
  remote 198.19.34.56 1194 udp
  </connection>
  
  <connection>
  remote 198.19.34.56 443 tcp
  </connection>
  
  <connection>
  remote 198.19.34.56 443 tcp
  http-proxy 192.168.0.8 8080
  </connection>
  
  <connection>
  remote 198.19.36.99 443 tcp
  http-proxy 192.168.0.8 8080
  </connection>
  
  persist-key
  persist-tun
  pkcs12 client.p12
  remote-cert-tls server
  verb 3
  

  Сперва мы попытаемся подключиться к серверу на 198.19.34.56:1194 через UDP. Если ошибка, то к 198.19.34.56:443 через TCP. Если опять ошибка, то сквозь HTTP прокси на 192.168.0.8:8080 попробуем подключиться к 198.19.34.56:443 по TCP. Наконец если снова ошибка, то через тот же прокси к 198.19.36.99:443 по TCP

  Следующие ниже OpenVPN опции могут быть использованы внутри блока <connection>:

  • bind
  • connect-retry
  • connect-retry-max
  • connect-timeout
  • explicit-exit-notify
  • float
  • fragment
  • http-proxy
  • http-proxy-option
  • link-mtu
  • local
  • lport
  • mssfix
  • mtu-disc
  • nobind
  • port
  • proto
  • remote
  • rport
  • socks-proxy
  • tun-mtu
  • tun-mtu-extra

  Вышеописанные опции могут находиться вне блока <connection>, тогда они будут считаться дефолтными для всех профилей (<connection> блоков) (кроме remote)

  For example, suppose the nobind option were placed in the sample configuration file above, near the top of the file, before the first <connection> block. The effect would be as if nobind were declared in all <connection> blocks below it

• --proto-force p - При итерации по профилям будут пробоваться только профили с тем же протолом что указан в этой опции (tcp/udp)

• --remote-random - Когда указано много remote или когда используются профили, эта опция сперва перемешает их для простой балансировки нагрузки

• --proto p - Указывает какой протокол нужно использовать для общения с remote. p может быть udp, tcp-client, tcp-server. Если эта опция не указана, то используется udp

  Для работы по UDP, опция --proto udp должна быть указана у обоих пиров

  Для работы по TCP, один пир должен иметь tcp-server, а другой tcp-client. Сервер будет ждать входящих подключений. А клиент будет пытаться подключиться, и если не выйдет то подождет 5 секунд (регулируется опцией --connect-retry) и попытается снова, и так бесконечно, либо N раз указанных в опции --connect-retry-max

  Both TCP client and server will simulate a SIGUSR1 restart signal if either side resets the connection

  OpenVPN создан чтобы оптимально работать по UDP, но возможность работы по TCP добавлена для ситуаций когда по UDP работать нельзя. В сравнении с UDP, TCP будет менее эффективным и менее быстрым в ненадежных или перегруженных сетях

  Статья о проблемах туннелирования IP поверх TCP - http://sites.inka.de/sites/bigred/devel/tcp-tcp.html

• --connect-retry n [max] - Указывает сколько секунд ждать между попытками подключения (default=5). После 5 попыток на каждый отдельный remote, интервал между попытками переподключения замедляется удваиваясь после каждой неудачной попытки. Опциональный аргумент max указывает максимальную длительность ожидания (default=300)

• --connect-retry-max n - n указывает максимальное количество попыток на каждый --remote или <connection>. Если указать 1, то каждый сервер будет попробован единожды. При успешном подключении этот счетчик обнуляется (default=unlimited)

• --http-proxy server port [authfile|'auto'|'auto-nct'] [auth-method] - Подключаться к remote сквозь HTTP прокси на server:port. Если HTTP требует Proxy-Authenticate, то файл authfile может содержать логин и пароль (на отдельных строках, тогда всего в файле две строки) либо "stdin" для ввода из консоли. Эти данные могут быть также указаны в конфиге опциями --http-proxy-user-pass. auth-method может быть "none", "basic" или "ntlm"

  HTTP Digest authentication is supported as well, but only via the auto or auto-nct flags (below)

  Флаг auto говорит OpenVPN автоматически определить auth-method и запросить необходимые данные через stdin или интерфейс управления
  Флаг auto-nct (no clear-text auth) заставляет OpenVPN автоматически определять auth-method (как с auto), но отвергать небезопасные протоколы, такие как HTTP Basic Authentication

• --http-proxy-option type [parm] - Устанавливает дополнительные опции для HTTP прокси. Этот флаг может быть установлен множество раз для установки различных дополнительных опций:

  • VERSION version - Set HTTP version number to version (default=1.0)
  • AGENT user-agent - Set HTTP "User-Agent" string to user-agent
  • CUSTOM-HEADER name content - Adds the custom Header with name as name and content as the content of the custom HTTP header

• --socks-proxy server [port] [authfile] - Аналогична опции --http-proxy, принимает в себя: server, port, credentials

• --resolv-retry n - Если резолв имени из --remote зафейлился, то повторять попытки разрезолвить имя n секунд перед окончательным выпаданием в ошибку. Можно прописать infinite вместо числа, тогда будет повторно пытаться бесконечно
  По-умолчанию как раз и стоит --resolv-retry infinite, можно отключить проставив n=0

• --float - Позволяет удаленному пиру менять свой IP и/или порт, как это происходит при работе с DHCP (это поведение по умолчанию когда не используется --remote). --float вместе с --remote позволяет OpenVPN сессии сперва подключаться к известному адресу из remote, далее если пакет приходит с нового адреса, при условии что все тесты проходят нормально, контроль над сессией переходит новому адресу. Это полезно когда ты подключен к пиру по адресу который ему выдан через DHCP. По факту флаг --float говорит OpenVPN принимать пакеты аутентификации с любого адреса, а не только с того который прописан в опции --remote

• --ipchange cmd - Запускает команду cmd когда твой ip адрес аутентифицирован или изменен. cmd содержит путь до скрипта или бинаря, с опциональными аргументами для него. Путь и аргументы могут быть закавычены или пробелы могут быть экранированы
  Когда запускается cmd, ему добавляются два аргумента (после всех аргументов) - cmd ip_address port_number
  Не используй --ipchange вместе с --mode server, вместо этого используй --client-connect
  Смотри секцию Environmental Variables для дополнительных параметров

  Если ты работаешь в среде с динамическими IP адресами, где пиры меняют адрес без уведомлений, можно использовать скрипт, который, например, будет приводить /etc/hosts к актуальному состоянию. Скрипт будет запускаться каждый раз, когда пир меняет адрес

  Similarly if our IP address changes due to DHCP, we should configure our IP address change script to deliver a SIGHUP or SIGUSR1 signal to OpenVPN. OpenVPN will then reestablish a connection with its most recently authenticated peer on its new IP address

• --port port - Номер или имя TCP/UDP порта для обоих пиров (чтобы задать разные используй --lport и --rport) (default=1194)

• --lport port - Устанавливает локальный TCP/UDP порт по номеру или имени. Не может быть использован вместе с опцией --nobind

• --rport port - Устанавливает TCP/UDP порт по номеру или имени для опции --remote. Этот порт может быть задан внутри опции --remote

• --bind [ipv6only] - Прибиндиться на локальный адрес и порт. Стоит по умолчанию если не просталено --proto tcp-client, --http-proxy или --socks-proxy. Если проставлен опциональный аргумент ipv6only, то OpenVPN прибиндится только на IPv6

• --nobind - Указывает OpenVPN не биндиться на локальный адрес. IP стек будет динамически выделять порт для получения пакетов. Эта опция подходит только для пиров которые будут инициировать подключение по опции --remote

• --dev tunX | tapX | null - Виртаульный сетевой интерфейс TUN/TAP (X может быть опущен для динамических девайсов). Нужно использовать одинаковый тип на обоих концах подключения (tun/tap). Нельзя миксовать их, потому что они работают на разных уровнях сети
  tun девайсы инкапсулируют IPv4 или IPv6 (Layer 3), тогда как tap девайсы инкапсулируют Ethernet 802.3 (Layer 2)

• --dev-type device-type - Какой тип интерфейса мы испольуем? device-type должен быть tun или tap. Используй эту опцию только когда указанное в опции --dev название девайса не начинается с tun или tap

• --topology mode - Конфигурирует топологию виртуальной адресации когда используется режим --dev tun. Эта директива не имеет смысла в режиме --dev tap, которая всегда работает по топологии subnet. Если указать эту директиву на сервере, то директивы --server и --server-bridge будут автоматически пушить выбранную тобой топологию клиентам. Эта директива может быть также вручную пропушена клиентам. Как и директива --dev, топология должна быть согласована с клиентами (эта опция должна быть одинаковой на обоих концах)
  mode может быть одним из:

  • net30 -