diff --git a/source/manual/how-tos/sslvpn_instance_roadwarrior.rst b/source/manual/how-tos/sslvpn_instance_roadwarrior.rst
new file mode 100644
index 00000000..8fdeda55
--- /dev/null
+++ b/source/manual/how-tos/sslvpn_instance_roadwarrior.rst
@@ -0,0 +1,216 @@
+=================================
+Setup SSL VPN Road Warrior
+=================================
+
+.. image:: images/sslvpn_image_new.png
+ :width: 100%
+
+Road Warriors are remote users who need secure access to the companies infrastructure.
+OPNsense uses OpenVPN for its SSL VPN Road Warrior setup and offers OTP (One Time Password)
+integration with standard tokens and Googles Authenticator.
+
+.. Tip::
+
+ Did you know that OPNsense offers two-factor authentication throughout the entire
+ system? See for more information: :doc:`/manual/two_factor`
+
+.. Note::
+
+ For the sample we will use a private IP for our WAN connection.
+ This requires us to disable the default block rule on wan to allow private traffic.
+ To do so, go to :menuselection:`Interfaces --> [WAN]` and uncheck "Block private networks".
+ *(Dont forget to save and apply)*
+
+ .. image:: images/block_private_networks.png
+
+
+.. contents:: Index
+
+----------------
+Before you start
+----------------
+Before starting with the configuration of an OpenVPN SSL tunnel you need to have a
+working OPNsense installation with a unique LAN IP subnet for each side of your
+connection (your local network needs to be different than that of the remote
+network).
+
+.. Note::
+
+ For the sample we will use a private IP for our WAN connection.
+ This requires us to disable the default block rule on WAN to allow private traffic.
+ To do so, go to :menuselection:`Interfaces --> [WAN]` and uncheck "Block private networks".
+ *(Don't forget to save and apply)*
+
+ .. image:: images/block_private_networks.png
+
+
+--------------------------------
+Network topology
+--------------------------------
+
+The schema below describes the situation we are implementing. One client using an "external" ip address of :code:`10.0.8.2/24`
+a firewall we are connecting to at :code:`10.0.8.1/24` constructing a tunnel using :code:`10.2.8.0/24` to reach :code:`192.168.8.0/24`.
+
+.. nwdiag::
+ :scale: 100%
+
+ nwdiag {
+
+ span_width = 90;
+ node_width = 180;
+ network {
+ address = "10.0.8.0/24";
+ pclana [label="Roadwarrior\n10.2.8.2",shape="cisco.pc"];
+ fw [shape = "cisco.firewall", address="10.0.8.1/24"];
+ }
+ network Ext {
+ address = "192.168.8.0/24";
+ fw [shape = "cisco.firewall", address="192.168.8.1/24"];
+ pclanb [label="Server\n192.168.8.20",shape="cisco.pc"];
+ }
+
+ }
+
+
+
+--------------------------------
+Preparations
+--------------------------------
+
+.....................
+Trust
+.....................
+
+
+In order to setup a tunnel on both ends, we need to configure certificates to warrant trust between the client and this server.
+
+* First we need an **Authority** which we are going to create in :menuselection:`System --> Trust --> Authorities`
+
+ * Select `Create an internal Certificate Authority`
+ * Choose cryptographic settings and a lifetime (you may want to increase the default as after this time you do need to redistribute certificates to both server and client).
+ * Add descriptive information for this CA (`Descriptive name`, `City`, `Email`, ..`)
+ * Set the `Common Name` to something descriptive for this certificate, like "Office-ovpn"
+
+
+* Next generate a **Certficate** for the server using :menuselection:`System --> Trust --> Certificates`
+
+ * Select `Create an internal Certificate`
+ * Choose the just created authority in `Certificate authority`
+ * Add descriptive information for this CA (`Descriptive name`, whereabouts are copied from the CA)
+ * Set Type to `Server`
+ * Choose cryptographic settings, lifetime determines the validaty of the server certificate (you do need to track this yourself), it's allow to choose a longer period here
+ * Set the `Common Name` to the fqdn of this machine.
+
+* For the client pc we will create a user and a certificate, from the :menuselection:`System --> Access --> Users` menu.
+
+ * Hit the [+] sign to create a new user, for this test we will call it :code:`test1`
+ * Check the "Certificate -> Click to create a user certificate" option and hit "save"
+ * Next step in the certificate window, select "`Create an internal Certificate`" and "save"
+
+
+.. Note::
+
+ It's a best practice to offer each user it's own certificate using the same common name as the username, although
+ it is also possible to clients to share a certificate. When adding a certificate from the user manager the CN is automatically
+ set to its name. In this example we will only authenticate using the certificate, no additional user or password will be required.
+
+
+.....................
+Static keys
+.....................
+
+We create a static key and define it's use in :menuselection:`VPN --> OpenVPN --> Instances --> Static Keys`, for this example
+select `auth` as mode and click the gear button to generate one. Provide a description for this key.
+
+
+
+------------------------------------
+Create a server instance
+------------------------------------
+
+Now the generic setup is done, we can configure a new server type instance via :menuselection:`VPN --> OpenVPN --> Instances`
+
+===============================================================
+
+======================= =======================================
+Property site B
+======================= =======================================
+Role Server
+Description MyServer
+Protocol UDP (IPv4)
+Port number 1194
+Bind address 10.10.8.1 :sup:`1`
+Server (IPv4) 10.1.8.0/24 (the tunnel network used)
+Certificate choose the prepared server certificate
+TLS static key choose the prepared static key
+Authentication Local Database :sup:`2`
+Strict User/CN Matching [V] :sup:`3`
+Local Network 192.168.8.0/24
+======================= =======================================
+
+.. admonition:: Note :sup:`1`
+
+ Leave empty to bind to all addresses assigned to this machine or use a loopback address combined with a port forward when
+ the external address is not static.
+
+.. admonition:: Note :sup:`2`
+
+ When users are also required to use a one-time-password, just select an authentication server that supports the additional
+ token.
+
+.. admonition:: Note :sup:`3`
+
+ Selecting the "Strict User/CN Matching" option warrants only matching user/certificate can login, when sharing a single
+ vertificate between clients this option needs to be deselected.
+
+
+Next go to :menuselection:`Firewall --> Rules --> WAN` and add a rule to allow traffic on port :code:`1494/UDP` from the other
+host. At minimum we should add a rule similar to this one:
+
+===============================================================
+
+======================= =======================================
+Property site B
+======================= =======================================
+Interface WAN
+Protocol UDP
+Destination port range 1194
+======================= =======================================
+
+Finally we are going to allow traffic on the tunnel itself by adding a rule to :menuselection:`Firewall --> Rules --> OpenVPN`,
+for this example we keep it simple and add one to allow all, in which case we can save the defaults when adding a rule.
+
+
+------------------------------------
+Export client profile
+------------------------------------
+
+With the server in place it's time to setup the client on OPNsense, for this we go to :menuselection:`VPN --> OpenVPN --> Client Export`
+and export a profile for the remote client.
+
+===================================================================
+
+======================= ===========================================
+Property Value
+======================= ===========================================
+Remote Access Server select the Roadwarrior server "MyServer"
+Export type File Only :sup:`1`
+Hostname 10.10.8.1
+======================= ===========================================
+
+.. admonition:: Note :sup:`1`
+
+ Most clients support the standard :code:`ovpn` format, when using a tool like Viscosity from Sparklabs (https://www.sparklabs.com/viscosity/)
+ you can also choose the proper type here.
+
+Next client on the certificate with link user in the grid below and install the certificate on the client.
+
+
+--------------------------------
+Test connectivity
+--------------------------------
+
+After connecting the client, use the :menuselection:`VPN: OpenVPN: Connection Status` page to watch the status of the connected
+client. It should show the client with byte counters.
+
+Now try to ping from Site A (:code:`10.0.8.20`) to Site B (:code:`192.168.8.20`).
diff --git a/source/manual/how-tos/sslvpn_instance_s2s.rst b/source/manual/how-tos/sslvpn_instance_s2s.rst
new file mode 100644
index 00000000..eac0f67f
--- /dev/null
+++ b/source/manual/how-tos/sslvpn_instance_s2s.rst
@@ -0,0 +1,224 @@
+=================================
+Setup SSL VPN site to site tunnel
+=================================
+
+Site to site VPNs connect two locations with static public IP addresses and allow
+traffic to be routed between the two networks. This is most commonly used to
+connect an organization's branch offices back to its main office, so branch users
+can access network resources in the main office.
+
+.. contents:: Index
+
+----------------
+Before you start
+----------------
+Before starting with the configuration of an OpenVPN SSL tunnel you need to have a
+working OPNsense installation with a unique LAN IP subnet for each side of your
+connection (your local network needs to be different than that of the remote
+network).
+
+.. Note::
+
+ For the sample we will use a private IP for our WAN connection.
+ This requires us to disable the default block rule on WAN to allow private traffic.
+ To do so, go to :menuselection:`Interfaces --> [WAN]` and uncheck "Block private networks".
+ *(Don't forget to save and apply)*
+
+ .. image:: images/block_private_networks.png
+
+
+--------------------------------
+Network topology
+--------------------------------
+
+The schema below describes the situation we are implementing. Two networks (A,B) and a transit network (10.10.8.0/24)
+to peer both firewalls. We will create a tunnel network :code:`10.1.8.0/24` between both sites.
+
+.. nwdiag::
+ :scale: 100%
+
+ nwdiag {
+
+ span_width = 90;
+ node_width = 180;
+ network A {
+ address = "10.0.8.0/24";
+ pclana [label="PC Site A\n10.0.8.20",shape="cisco.pc"];
+ fwa [shape = "cisco.firewall", address="10.0.8.1/24"];
+ }
+ network Ext {
+ address = "10.10.8.0/24";
+ label = "Tunnel net 10.1.8.0/24";
+ fwa [shape = "cisco.firewall", address="10.10.8.1/24"];
+ fwb [shape = "cisco.firewall", address="10.10.8.2/24"];
+ }
+ network B {
+ address = "192.168.8.0/24"
+ fwb [shape = "cisco.firewall", address="192.168.8.20"];
+ pclanb [label="PC Site B\n192.168.8.20",shape="cisco.pc"];
+ }
+
+
+ }
+
+
+
+--------------------------------
+Preparations
+--------------------------------
+
+.....................
+Trust
+.....................
+
+
+In order to setup a tunnel on both ends, we need to configure certificates to warrant trust between both machines.
+We have chosen to setup the server on "Site B", so we start with Trust configuration there.
+
+* First we need an **Authority** which we are going to create in :menuselection:`System --> Trust --> Authorities`
+
+ * Select `Create an internal Certificate Authority`
+ * Choose cryptographic settings and a lifetime (you may want to increase the default as after this time you do need to redistribute certificates to both server and client).
+ * Add descriptive information for this CA (`Descriptive name`, `City`, `Email`, ..`)
+ * Set the `Common Name` to something descriptive for this certificate, like "Office-ovpn"
+
+
+* Next generate a **Certficate** for the server using :menuselection:`System --> Trust --> Certificates`
+
+ * Select `Create an internal Certificate`
+ * Choose the just created authority in `Certificate authority`
+ * Add descriptive information for this CA (`Descriptive name`, whereabouts are copied from the CA)
+ * Set Type to `Server`
+ * Choose cryptographic settings, lifetime determines the validaty of the server certificate (you do need to track this yourself), it's allow to choose a longer period here
+ * Set the `Common Name` to the fqdn of this machine.
+
+* As the client (Site A) will also need a **Certificate**, we need to create a certificate, also using :menuselection:`System --> Trust --> Certificates`
+
+ * Select `Create an internal Certificate`
+ * Choose the just created authority in `Certificate authority`
+ * Add descriptive information for this CA (`Descriptive name`, whereabouts are copied from the CA)
+ * Set Type to `Server`
+ * Choose cryptographic settings, lifetime determines the validaty of the server certificate (you do need to track this yourself), it's allow to choose a longer period here
+ * Set the `Common Name` to username the other end will use for identification. For this example we use :code:`test-client`
+
+.. Note::
+
+ It's a best practice to offer each user it's own certificate using the same common name as the username, although
+ it is also possible to clients to share a certificate. When adding a certificate from the user manager the CN is automatically
+ set to its name. In this example we will only authenticate using the certificate, no additional user or password will be required.
+
+
+.....................
+Static keys
+.....................
+
+We create a static key and define it's use in :menuselection:`VPN --> OpenVPN --> Instances --> Static Keys`, for this example
+select `auth` as mode and click the gear button to generate one. Provide a description for this key.
+
+..........................................
+Prepare Site A
+..........................................
+
+* Copy the public part of the certificate authority to the firewall at Site a (use the download button and copy the contents into a new CA on this host)
+* Copy the public and private part of the client certificate into a new one on Site A
+* Copy the contents of the static key to a new entry and select the same type
+
+
+------------------------------------
+Create a server instance (Site B)
+------------------------------------
+
+Now the generic setup is done, we can configure a new server type instance via :menuselection:`VPN --> OpenVPN --> Instances`
+
+===============================================================
+
+======================= =======================================
+Property site B
+======================= =======================================
+Role Server
+Description MyServer
+Protocol UDP (IPv4)
+Port number 1194
+Bind address 10.10.8.1 :sup:`1`
+Server (IPv4) 10.1.8.0/24 (the tunnel network used)
+Certificate choose the prepared server certificate
+TLS static key choose the prepared static key
+Local Network 192.168.8.0/24
+Remote Network 10.0.8.0/24 :sup:`2`
+======================= =======================================
+
+.. admonition:: Note :sup:`1`
+
+ Leave empty to bind to all addresses assigned to this machine or use a loopback address combined with a port forward when
+ the external address is not static.
+
+.. admonition:: Note :sup:`2`
+
+ The network(s) served by this openvpn instance, after startup routes will be created. In order to bind
+ the network to the correct client a `Client Specific Overwrite` is also needed.
+
+
+Hit the apply button when the instance is configured and add a client specific overwrite in :menuselection:`VPN --> OpenVPN --> Client Specific Overrides`
+
+===============================================================
+
+======================= =======================================
+Property site B
+======================= =======================================
+Servers leave empty or select our server
+Common name test-client
+Remote Network 10.0.8.0/24 :sup:`1`
+======================= =======================================
+
+.. admonition:: Note :sup:`1`
+
+ The remote network bound to this common name, without this entry the traffic will not be routed between hosts.
+
+
+Next go to :menuselection:`Firewall --> Rules --> WAN` and add a rule to allow traffic on port :code:`1494/UDP` from the other
+host. At minimum we should add a rule similar to this one:
+
+===============================================================
+
+======================= =======================================
+Property site B
+======================= =======================================
+Interface WAN
+Protocol UDP
+Destination port range 1194
+======================= =======================================
+
+Finally we are going to allow traffic on the tunnel itself by adding a rule to :menuselection:`Firewall --> Rules --> OpenVPN`,
+for this example we keep it simple and add one to allow all, in which case we can save the defaults when adding a rule.
+
+
+------------------------------------
+Create a client instance (Site A)
+------------------------------------
+
+With the server in place it's time to setup the client on OPNsense, for this we go to :menuselection:`VPN --> OpenVPN --> Instances`
+and add a new instance using the following settings.
+
+===============================================================
+
+======================= =======================================
+Property site A
+======================= =======================================
+Role Client
+Description MyClient
+Protocol UDP (IPv4)
+Remote 10.10.8.1
+Certificate choose the prepared client certificate
+TLS static key choose the prepared static key
+Remote Network 192.168.8.0/24
+======================= =======================================
+
+
+--------------------------------
+Test connectivity
+--------------------------------
+
+Use the :menuselection:`VPN: OpenVPN: Connection Status` page to watch the status of both server and client, when
+passing traffic over the link on both ends the counters should increase.
+
+Now try to ping from Site A (:code:`10.0.8.20`) to Site B (:code:`192.168.8.20`).
diff --git a/source/manual/vpnet.rst b/source/manual/vpnet.rst
index bf98d481..81b42aa7 100644
--- a/source/manual/vpnet.rst
+++ b/source/manual/vpnet.rst
@@ -353,37 +353,120 @@ One of the main advantages of OpenVPN in comparison to IPsec is the ease of conf
and it's quite simple to export settings for clients.
.................................
-Site 2 Site
+General context
.................................
-OpenVPN on OPNsense can also be used to create a tunnel between two locations, similar to what IPsec offers. Generally
-the performance of IPsec is higher which usually makes this a less common choice.
-
-.. toctree::
- :maxdepth: 2
- :titlesonly:
+The OpenVPN module incorporates different functions to setup secured networks for roadwarriors and side to side connections.
+Since the start of our project we organized the openvpn menu section into servers and clients, which actually is a role
+for the same OpenVPN process. As our legacy system has some disadvantages which are difficult to fix in a migration, we have chosen
+to add a new component named :code:`Instances` in version 23.7 which offers access to OpenVPN's configuration in a similar way as
+the upstream `documentation `__ describes it.
+This new component will eventually replace the existing client and server options in a future version of OPNsense, leaving
+enough time to migrate older setups.
- how-tos/sslvpn_s2s
+.. Tip::
+ When upgrading into a new major version of OPNsense, always make sure to read the release notes to check if your setup
+ requires changes.
.. Note::
- When using the site to site example with :code:`SSL/TLS` instead of a shared key, make sure to configure "client specific overrides"
- as well to correctly bind the remote networks to the correct client.
+ OpenVPN on OPNsense can also be used to create a tunnel between two locations, similar to what IPsec offers. Generally
+ the performance of IPsec is higher which usually makes this a less common choice.
+ Mobile usage is really where OpenVPN excells, with various (multifactor) authentication options and
+ a high flexibility in available network options.
+
+
+The following functions are available in the menu (as of OPNsense 23.7):
+
+* Instances
+
+ * New instances tool offering access to server and client setups
+
+* Servers
+
+ * Legacy server configuration tool
+
+* Clients
+
+ * Legacy client configuration tool
+
+* Client Specific Overrides
+
+ * Set client specific configurations based on the client’s X509 common name.
+
+* Client Export
+
+ * Export tool for client configurations, used for server type instances
+
+* Connection Status
+
+ * Show tunnel statusses
+
+* Log File
+
+ * Inspect log entries related to OpenVPN
+
+
+....................................
+Public Key Infrastructure (X.509)
+....................................
+
+OpenVPN is most commonly used in combination with a public key infrastructure, where we use a certificate autority which
+signs certificates for both server and clients (Also know as TLS Mode).
+More information about this topic is available in our :doc:`Trust section `.
.................................
-Road Warriors / Mobile users
+Firewall rules
.................................
-Mobile usage is really where OpenVPN excells, with various (multifactor) authentication options and a high flexibility in available network options.
+To allow traffic to the tunnel on any interface, a firewall rule is needed to allow the tunnel being established.
+The default port for OpenVPN is :code:`1194` using protocol :code:`UDP`.
+
+After communication has been established, it's time to allow traffic inside the tunnel. All OpenVPN interfaces defined in
+OPNsense are :doc:`grouped ` as `OpenVPN`.
+
+.. Tip::
+
+ In order to use features as policy based routing or manual routes, you can :doc:`assign ` the underlying
+ devices and use them in a similar fashion as physical interfaces.
+
+
+.................................
+Examples
+.................................
+
+This paragraph offers examples for some commonly used implementation scenarios.
+
+.. Note::
+
+ When using a site to site example with :code:`SSL/TLS` instead of a shared key, make sure to configure "client specific overrides"
+ as well to correctly bind the remote networks to the correct client.
+
+
+Legacy (:menuselection:`VPN -> OpenVPN -> Client|Server`)
+------------------------------------------------------------------------------
.. toctree::
:maxdepth: 2
:titlesonly:
+ how-tos/sslvpn_s2s
how-tos/sslvpn_client
+New (:menuselection:`VPN -> OpenVPN -> Instances`)
+------------------------------------------------------------------------------
+
+.. toctree::
+ :maxdepth: 2
+ :titlesonly:
+
+ how-tos/sslvpn_instance_s2s
+ how-tos/sslvpn_instance_roadwarrior
+
+
+
.................................
Client Specific Overrides
.................................