{"id":13489243,"url":"https://github.com/OpenVPN/openvpn3-linux","last_synced_at":"2025-03-28T04:30:59.547Z","repository":{"id":40743348,"uuid":"114954159","full_name":"OpenVPN/openvpn3-linux","owner":"OpenVPN","description":"OpenVPN 3 Linux client - This is a mirror of https://codeberg.org/OpenVPN/openvpn3-linux/","archived":false,"fork":false,"pushed_at":"2025-03-11T12:10:44.000Z","size":5562,"stargazers_count":587,"open_issues_count":19,"forks_count":153,"subscribers_count":42,"default_branch":"master","last_synced_at":"2025-03-11T13:23:47.627Z","etag":null,"topics":["dbus","linux","openvpn","security","vpn","vpn-client","vpn-tunnel"],"latest_commit_sha":null,"homepage":"https://codeberg.org/OpenVPN/openvpn3-linux/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenVPN.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-12-21T02:43:12.000Z","updated_at":"2025-03-11T12:10:52.000Z","dependencies_parsed_at":"2024-08-28T08:53:27.176Z","dependency_job_id":"d64cf93b-2171-4b48-a962-335202fee888","html_url":"https://github.com/OpenVPN/openvpn3-linux","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVPN%2Fopenvpn3-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVPN%2Fopenvpn3-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVPN%2Fopenvpn3-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenVPN%2Fopenvpn3-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenVPN","download_url":"https://codeload.github.com/OpenVPN/openvpn3-linux/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245970381,"owners_count":20702398,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dbus","linux","openvpn","security","vpn","vpn-client","vpn-tunnel"],"created_at":"2024-07-31T19:00:20.929Z","updated_at":"2025-03-28T04:30:59.539Z","avatar_url":"https://github.com/OpenVPN.png","language":"C++","readme":"OpenVPN 3 Linux\n===============\n\nOpenVPN 3 Linux is an OpenVPN platform which builds on capabilities\navailable on newer Linux distributions.  Compared to the more classic\nOpenVPN 2.x generation, OpenVPN 3 Linux covers many more aspects of the\nVPN configuration and session life-cycle than prior OpenVPN generations did.\n\nTo quickly compare them, OpenVPN 2.x provides a single executable which\nis responsible for a single VPN session.  There are no configuration or\nsession management in OpenVPN 2.x itself, it depends on the systemd\n`openvpn-client@.service` and `openvpn-server@.service` unit files, the\nNetwork Manager OpenVPN plug-in or other third-party management tools.\n\nOpenVPN 3 Linux provides full configuration and session management in\naddition to providing the VPN tunnel itself.  For example, it has built in\nprivilege separation and execution models, for improved process security.\nThis allows unprivileged users to start their own VPN sessions and manage\nthem themselves.  VPN configuration profiles can be shared with other users\non the system or kept private.  All without installing anything\nadditionally.\n\nThrough this privilege separation model, the network configuration aspect\nof the VPN tunnel is split out into its own process which runs with as few\nprivileges as possible.  In practice that means it can only do network\nconfiguration changes.  This process knows nothing about the connection\nto the VPN server, it just facilitates creating the virtual network adapter\nand configuring it with network routes.  This network configuration service\nis also capable of setting up the DNS resolver out-of-the-box.  For\nOpenVPN 2.x to do that, it would need to run additional scripts or use\nspecific plug-ins to trigger such updates on the system.\n\nThe same OpenVPN 3 Core library which is used in the OpenVPN Connect\nclients is also used in this project.  This implementation does not support\nall options OpenVPN 2.x does, but if you have a functional configuration\nwith OpenVPN Connect (typically on Android or iOS devices) it should work\nwith this client.  In general OpenVPN 3 supports routed TUN configurations;\nTAP and bridged setups are not supported and will not work.\n\nThe OpenVPN 3 Linux architecture is based on splitting up the functionality\ninto several independently running services.  They are referred to as\n*backend services*.  The interaction with these services happens through\nwhat is referred to as a *user front-end*.  This project also ships\nwith a Python 3 module which can be used to implement your own OpenVPN\nfront-ends.\n\nOn a more technical level, the integration between the *user front-end* and\nthe *backend services* is built on top of D-Bus.  Any programming language\nsupporting D-Bus can also be used to extend and implement a richer\nfunctionality.\n\n\nPre-built binaries\n-----------------\n\nSee the instructions on\nhttps://community.openvpn.net/openvpn/wiki/OpenVPN3Linux how to install\npre-built OpenVPN 3 Linux packages on Debian, Ubuntu, Fedora and\nRed Hat Enterprise Linux.\n\n\nGetting started using OpenVPN 3 Linux\n-------------------------------------\n\nSee the [QUICK-START](QUICK-START.md) document to get started using\nOpenVPN 3 Linux.\n\n\nIntroduction to the OpenVPN 3 Linux architecture\n------------------------------------------------\n\nTo interact with the various OpenVPN 3 services running in the background,\nthree different utilities are provided.\n\n* `openvpn2`\n  ([man page](docs/man/openvpn2.1.rst))\n\n  This is an interface which tries to look and behave more like the classic\n  OpenVPN 2.x versions.  It does only allow options which are supported by\n  the OpenVPN 3 Core Library, plus there are a handful options which are\n  ignored as it is possible to establish connections without those options\n  active.  Only client side options are supported.\n\n  When running openvpn2 with `--daemon` it will return a D-Bus session path\n  to the VPN session.  This path can be used by the `openvpn3` utility to\n  further manage this session.\n\n* `openvpn3`\n  ([man page](docs/man/openvpn3.1.rst))\n\n  This is a brand new command line interface which does not look like\n  OpenVPN 2.x at all.  It can be used to start, stop, pause, resume tunnels\n  and retrieve tunnel statistics.  It can also be used as import, retrieve\n  and manage configurations stored in the configuration manager, as well as\n  handling access control lists for VPN configuration profiles and running\n  VPN sessions.\n\n* `openvpn3-admin`\n  ([man page](docs/man/openvpn3-admin.8.rst))\n\n  This will mostly only work when run as `root`.  This is used to adjust\n  some settings or retrieve information for some of the backend services\n  and related system administration tasks.\n\nAs mentioned earlier, the OpenVPN 3 Linux project is built on top of D-Bus.\nThis provides an API which can be used to further interact with the\nOpenVPN 3 Linux stack.  It can be used to create a new user front-end or\nit can be used to trigger other operations on the host when certain events\nhappens.\n\nThe OpenVPN 3 Linux stack consists of several D-Bus services running in the\nbackground.  There are six services which is good to beware of.  All of\nthese services will normally start automatically.  And when they are idle\nfor a while with no data to maintain, they will shut-down automatically.\n\n* `openvpn3-service-configmgr`\n   ([man page](docs/man/openvpn3-service-configmgr.8.rst) | [D-Bus documentation](docs/dbus/dbus-service-net.openvpn.v3.configuration.md))\n\n  This is the configuration manager.  All configuration profiles will be\n  uploaded to and managed by this service before a tunnel is started.  This\n  service also ensures only users granted access to imported VPN profiles\n  has the proper access to them.  By default this process is started as\n  the `openvpn` user.\n\n* `openvpn3-service-sessionmgr`\n  ([man page](docs/man/openvpn3-service-sessionmgr.8.rst) | [D-Bus documentation](docs/dbus/dbus-service-net.openvpn.v3.sessions.md))\n\n  This manages all VPN tunnels which are about to start or has started.  It\n  takes care of communicating with the VPN backend processes and ensures\n  only users with the right access levels can manage the various tunnels.\n  This service is started as the `openvpn` user.\n\n* `openvpn3-service-backendstart`\n  ([man page](docs/man/openvpn3-service-backendstart.8.rst) | [D-Bus documentation](docs/dbus/dbus-service-net.openvpn.v3.backends.md))\n\n  This is a helper service and is only availble for the session manager.\n  The only task this service has is to start a new VPN client backend\n  processes (the VPN tunnel instances).  By default this is also started\n  as the `openvpn` user.\n\n* `openvpn3-service-client`\n  ([man page](docs/man/openvpn3-service-client.8.rst) | [D-Bus documentation](docs/dbus/dbus-service-net.openvpn.v3.client.md))\n\n  This must be started by the `openvpn3-service-backendstart` service.  One\n  such process is started per VPN client.  Once it has started, it registers\n  itself with the session manager and the session manager provides it with\n  the needed details so it can retrieve the proper configuration profile\n  from the configuration manager.  This service will depend on the\n  `openvpn3-service-netcfg` to manage the tun interface and related\n  configuration.  This service is started as the `openvpn` users.\n\n* `openvpn3-service-netcfg`\n  ([man page](docs/man/openvpn3-service-netcfg.8.rst) | [D-Bus documentation](docs/dbus/dbus-service-net.openvpn.v3.netcfg.md))\n\n  This provides a service similar to a VPN API on some platforms.  It\n  is responsible for creating, managing and destroying of virtual tunnel\n  interfaces, such as the `tun` or `ovpn`  Data Channel Offload interfaces.\n  It will also configure them in addition to handle the DNS configuration\n  provided by the VPN server.  This is the most privileged process which\n  only have a few capabilities enabled (such as `CAP_NET_ADMIN` and\n  possibly `CAP_DAC_OVERRIDE` or `CAP_NET_RAW`).  With these capabilities,\n  the service can run as the `openvpn` user.\n\n  Currently DNS configuration is done by manipulating `/etc/resolv.conf`\n  directly.  Support for `systemd-resolved` has been added.  On Linux\n  distrubutions expected to be pre-configured with `systemd-resolved`,\n  OpenVPN 3 Linux will use this service.  On other distributions this need\n  to be enabled manually by running the following command as `root`:\n\n      # openvpn3-admin netcfg-service --config-set systemd-resolved true\n\n  Next time the ``openvpn3-service-netcfg`` service restarts,\n  `systemd-resolved` support will be used instead.  Note, this requires at\n  least **systemd v243** or newer (or a distribution which has back-ported\n  a newer version).  This works now with Fedora 31 and newer,\n  Red Hat Enterprise Linux 8 or Ubuntu 20.04 and newer.\n\n  To disable the `systemd-resolved` integration and use `/etc/resolv.conf`\n  instead, run these commands as `root`:\n\n      # openvpn3-admin netcfg-service --config-unset systemd-resolved\n      # openvpn3-admin netcfg-service --config-set resolv-conf /etc/resolv.conf\n\n* `openvpn3-service-logger`\n  ([man page](docs/man/openvpn3-service-logger.8.rst) | [D-Bus documentation](docs/dbus/dbus-service-net.openvpn.v3.log.md))\n\n  This service will listen for log events happening from all the various\n  services in the OpenVPN 3 Linux stack.  It supports writing these events\n  to the console (stdout), files or redirect to syslog or the\n  `systemd-journald`.  This is also automatically started  when needed, if\n  it isn't already running.\n\nMore information can be found in the [`openvpn3-linux(7)`](docs/man/openvpn3-linux.7.rst)\nman page and [OpenVPN 3 D-Bus overview](docs/dbus/dbus-overview.md).\n\n\n\n####  Kernel based Data Channel Offload (DCO) support\n\nThe Data Channel Offload support moves the processing of the OpenVPN data\nchannel operations from the client process to the kernel, via the ovpn-dco-v2\nkernel module.  This means the encryption and decryption of the tunnelled\nnetwork traffic is kept entirely in kernel space instead of being send\nback and forth between the kernel and the OpenVPN client process.  This\nhas the potential to improve the overall VPN throughput.  This module must\nbe installed before OpenVPN 3 Linux can make use of this feature.  This is\nshipped in the OpenVPN 3 Linux package repositories or can be built from\nthe [source code](https://gitlab.com/openvpn/ovpn-dco/).\n\nThe ovpn-dco kernel module currently only support ***Linux kernel 5.4***\nand newer.  Currently supported distributions with DCO support:\n\n * Debian 11 and newer\n * Fedora 38 and newer\n * Red Hat Enterprise Linux 8 and newer\n * Ubuntu 20.04 and newer\n\n#### SELinux support\n\nThe `openvpn3-service-netcfg` service depends on being able to pass a file\ndescriptor to the tun device it has created on behalf of the\n`openvpn3-service-client` service (where each of these processes represents\na single VPN session).  This is done via D-Bus.  But on systems with\nSELinux, the D-Bus daemon is not allowed to pass file descriptors related\nto `/dev/net/tun`.\n\nThe OpenVPN 3 Linux project ships two SELinux policy modules, which will be\ninstalled in `/usr/share/selinux/packages`.\n\nThe `openvpn3.pp` policy package adds a SELinux boolean,\n`dbus_access_tuntap_device`, which grants processes, such as `dbus-daemon`\nor `dbus-broker` daemon (running under the `system_dbusd_t` process context)\naccess to files labelled as `tun_tap_device_t`; which matches the label of\n`/dev/net/tun`.  Without this policy enabled, the `openvpn3-service-netcfg`\nservice will not be able to create or manage TUN devices.\n\nTo install and activate this SELinux security module, as root run:\n\n         # semodule -i /etc/openvpn3/selinux/openvpn3.pp\n         # semanage boolean --m --on dbus_access_tuntap_device\n\nFor users installing the pre-built RPM binaries, this is handled by the RPM\nscriptlet during package install.\n\nThe second policy module, `openvpn3_service.pp`, will confine both the\n`openvpn3-service-netcfg` and `openvpn3-service-client` processes into their\nown SELinux process contexts (`openvpn3_netcfg_t` and `openvpn3_client_t`).\nSee the [`src/selinux/openvpn3_service.te`](src/selinux/openvpn3_service.te)\nsource for more details.\n\nFor the RPM builds, both SELinux policies are provided in the\n`openvpn3-selinux` package.\n\n\nLogging\n-------\n\nLogging happens via `openvpn3-service-logger`.  If not started manually,\nit will automatically be started by the backend processes needing it.  The\ndefault configuration sends log data to syslog or systemd-journald,\ndepending on the Linux distribution.  Unless `--syslog`, `--journald`  or\n`--log-file` is provided, it will log to the console (stdout).\n\nReal-time log events can be received on a per-session level, by using the\n[`openvpn3 log`](docs/man/openvpn3-log.1.rst) command.\n\nThis log service is managed via\n[`openvpn3-admin log-service`](docs/man/openvpn3-admin-log-service.8.rst.in).\nFor systems using `systemd-journald`, the\n[`openvpn3-admin journal`](docs/man/openvpn3-admin-journal.8.rst) command\nprovides a convenient approach to retrive only OpenVPN 3 Linux related log\nentries from the systemd journal.\n\nFor more information about logging, see the\n[`openvpn3-service-logger(8)`](docs/man/openvpn3-service-logger.8.rst),\nman page, [D-Bus Logging](docs/dbus/dbus-logging.md) and\n[`net.openvpn.v3.log` D-Bus service](docs/dbus/dbus-service-net.openvpn.v3.log.md)\ndocumentation.\n\n\nDebugging\n---------\n\nFor information about debugging, please see [docs/debugging.md](docs/debugging.md)\n\n\nBuilding from source\n--------------------\n\nFor information about building OpenVPN 3 Linux from source, please\nsee [BUILD.md](BUILD.md).\n\n\nContribution\n------------\n\n* Code contributions\n  Code contributions are most welcome.  Please submit patches for review\n  to the openvpn-devel@lists.sourceforge.net mailing list.  All patches must\n  carry a Signed-off-by line and must be reviewed publicly before acceptance.\n  Pull requests are not acceptable unless it is for early reviews and patch\n  discussions.  Final patches *MUST* go to the mailing list.\n\n* Testing\n  This code is quite new, but has been used a lot in various setups.\n  Please reach out on libera.chat @ #openvpn for help and discussing issues\n  you encounter, or subscribe to and ask on the\n  openvpn-users@lists.sourceforge.net mailing list.\n\n* Packagers\n  We are beginning to targeting packaging in Linux distributions.  The\n  Fedora Copr repository is one which is currently available.  We are\n  looking for people willing to package this in other Linux distributions\n  as well.\n","funding_links":[],"categories":["C++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenVPN%2Fopenvpn3-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FOpenVPN%2Fopenvpn3-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FOpenVPN%2Fopenvpn3-linux/lists"}