{{{
#!rst
Tapctl Network Interface Management Utility
===========================================


Introduction
------------

The Tapctl or ``tapctl.exe`` is a command line utility introduced in OpenVPN 2.5 to manage TAP network interfaces on Windows. It was developed to replace the ``tapinstall.exe`` utility.


User Manual
-----------

The Tapctl utility requires elevation. Please, run it from an elevated command prompt (Run as Administrator).


Creating a TAP/TUN network interface
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Usage::

  tapctl create [--name <desired interface name>]

A new virtual network interface is created.

When the ``--name`` parameter is omitted, Windows selects a name automatically (e.g. "Ethernet 2").

When the ``--name`` parameter is specified, the utility will rename the newly created interface to the name given. Should the interface with the given name already exist, an error is returned. If the name contains spaces, enclose it in quotes.

Upon successful creation, the newly created interface's GUID is output to stdout.

Notes:
  1. The name specified using ``--name`` parameter can also be specified as OpenVPN's ``--dev-node`` option.
  2. Tapctl does not install or update TAP-Windows driver. It assumes the driver is already installed. The TAP-Windows NDIS 6 driver is installed as a part of OpenVPN MSI setup or may be installed manually using the INF file. 


Listing installed TAP interfaces
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Usage::

  tapctl list

This command prints installed TAP network interfaces to stdout. The list will contain interface GUIDs and names.


Removing a TAP interface
^^^^^^^^^^^^^^^^^^^^^^^^

Usage::

  tapctl delete <interface GUID | interface name>

Deletes the specified TAP interface.


Developer Notes
---------------

The Tapctl utility was developed to compile using Microsoft Visual Studio 2017 and later upgraded to support building as a part of the OpenVPN-build system.

Source files
^^^^^^^^^^^^

``basic.h``
  Basic macro declarations

``error.c`` and ``error.h``
  OpenVPN compatible error reporting API. Though the Tapctl utility does not rely on ``openvpn.exe``'s source code, it borrows the run-time information output scheme from it. This tries to keep the source code style and best practices as close to OpenVPN as possible.

``main.c``
  Main utility logic. It also includes implementation of ``msg()`` function to output any messages to stdout and stderr. 

``tap.c`` and ``tap.h``
  Windows network interface management functions. All definitions in ``tap.h`` include description and usage instructions in a Doxygen form.

Except the ``main.c``, all of these source files are reused by the ``openvpnmsica`` DLL.
}}}