************ Client Setup ************ With :doc:`setup-controller` complete, the next step is to install a Bowtie *Client* that will connect to a Controller endpoint. The outline for this process is: #. Perform any pre-flight checks by checking :ref:`client-requirements` #. :ref:`client-download`. Bowtie supports Linux, Windows, and OS X. #. :ref:`Install the Client `. #. Perform necessary :ref:`client-configuration`. A Controller ``https`` endpoint is required unless using :ref:`a pre-configured package `. - :ref:`login-client` as part of initial setup. This step ensures that your organizational *identity* is properly associated with the connected device. #. :ref:`Accept ` the Client on the Controller. Note that this action may need to be performed by a user with administrative privileges and may be performed :ref:`before ` or :ref:`after ` client setup. **Step Summary** .. contents:: :local: :class: this-will-duplicate-information-and-it-is-still-useful-here .. _client-requirements: Client System Requirements ========================== - :ref:`windows-requirements` - :ref:`macos-requirements` - :ref:`linux-requirements` - :ref:`ubuntu-requirements` - :ref:`centos-stream-requirements` .. _windows-requirements: Windows Requirements -------------------- Bowtie is tested against Windows 11 update 22H2 and should work with Windows 7, 8, 10 and 11. As part of required dependencies, the client package will install Wireguard and Microsoft's WebView2 before completing its own installation. No manual steps required for these dependent packages. .. _macos-requirements: MacOS Requirements ------------------ Bowtie is tested against MacOS 13 "Ventura" and should work on MacOS versions 10.14, 10.15, 11, 12 and 13. MacOS packages are provided as ``.pkg`` files. .. _linux-requirements: Linux Requirements ------------------ Client packages will work on most Linux distributions but are currently only tested on Ubuntu 22.04 and CentOS Stream 9. If your distribution does not use ``.deb`` or ``.rpm`` packages, reach out to a Bowtie representative for additional support. Linux installations that have ``systemd-resolved`` enabled should work without additional configuration. Linux distributions *without* ``systemd-resolved`` enabled will likely work but may require further configuration. While Ubuntu and CentOS Stream are the only distributions currently supported by Bowtie client packages, the client is known to work on other distributions that provide commonly-available shared libraries. - :ref:`ubuntu-requirements` - :ref:`centos-stream-requirements` .. admonition:: Supported Distributions :class: note If your environment requires different Client packaging formats, let us know! We’d like to learn about your requirements to broaden compatibility. .. _ubuntu-requirements: Ubuntu ^^^^^^ Bowtie clients are distributed as ``.deb`` packages. The ``.deb`` package includes dependencies on ``iproute2``, ``wireguard``, ``net-tools``, ``libssl3``, ``libayatana-appindicator3-1``, and ``libgtk-3-0``. If you are not installing the ``.deb`` package you may need to install corresponding packages manually. Wireguard includes a kernel module. Bowtie also requires read access to ``sysfs``. Dependencies for ``libayatana`` and ``libgtk-3`` support a system tray applet. If you do not require the tray applet, the Bowtie client will still function but you may observed reduced functionality or convenience. Outside of Ubuntu, you may optionally install ``libappindicator3-1`` directly instead of the Ubuntu ``ayatana`` variant. .. _centos-stream-requirements: CentOS Stream ^^^^^^^^^^^^^ Bowtie clients are distributed as ``.rpm`` packages. Some dependencies unavailable in default CentOS Stream repositories require `EPEL `_ packages and so we recommend installing the ``epel-release`` package prior to installing the Bowtie client package: .. code:: yum install epel-release Although the Bowtie client will operate without a system tray available, we recommend installing `a GNOME extension to add system tray support `_ to make full use of client capabilities like assisted support and help diagnostics. .. _client-installation: Client Installation =================== .. _client-download: Download the Client ------------------- Use the Bowtie package distribution page to acquire the latest client package for your operating system. - `MacOS installer `_ - `Windows installer `_ - `Ubuntu Linux package `_ - `CentOS Stream package `_ You may append ``/latest`` to each URL if you would prefer to download the latest stable package directly, for example, https://api.bowtie.works/platforms/MacOS/latest. See :doc:`bowtie-get` if you need additional information about downloading clients. .. _per-client-packages: .. admonition:: Pre-configured packages :class: tip If you are a current customer, Bowtie can provide pre-configured Client packages that automatically connect to a desired Controller endpoint with any post-installation configuration step. Reach out to a Bowtie representative if you would like to opt-in to this service. Install the Client ------------------- Follow the instructions for your target operating system: - :ref:`windows-installation` - :ref:`macos-installation` - :ref:`linux-installation` .. _windows-installation: Windows Installation ^^^^^^^^^^^^^^^^^^^^ Double click on the ``.msi`` file after :ref:`downloading it ` to start installation. The installation wizard will start: .. image:: _static/windows-initial-wizard.png :scale: 40% :align: center After clicking *Install*, proceed to read and accept the license agreement: .. image:: _static/windows-agreement.png :scale: 40% :align: center The installer will continue. Read and follow any instructions provided by the installer during the course of installation. .. image:: _static/windows-wizard-progress.png :scale: 40% :align: center After the installer has finished, a final dialogue box will open with a *Launch* button to begin the software. .. image:: _static/windows-launch.png :scale: 40% :align: center Click this button to proceed with any necessary :ref:`configuration steps `. .. admonition:: Windows Firewall :class: note After the Bowtie client starts running, you will likely receive a notification from Windows Firewall asking for permission to allow network connectivity to and from ``bowtie-service.exe`` and ``bowtie-dns.exe``. Allow these two applications access to the network to permit full functionality. .. _macos-installation: MacOS Installation ^^^^^^^^^^^^^^^^^^ Double click on the downloaded ``Bowtie.pkg`` file to install Bowtie: .. image:: _static/macos-pkg.png The installation process will start. Click *Continue*: .. image:: _static/macos-install-initial.png Select an installation path for the program: .. image:: _static/macos-install-path.png Enter administrative credentials to install the software: .. image:: _static/macos-install-auth.png The installation setup may ask for additional folder permissions as part of the installation process. Click *Ok* to allow this: .. image:: _static/macos-install-folder.png The installer will continue and eventually complete. .. image:: _static/macos-install-complete.png Note that you may see a notification about the ``bowtie-ctl`` program being available after the installation has completed. This can safely be dismissed. .. image:: _static/macos-install-notif.png Once the installer exits, the :ref:`client-configuration` window will open, and you may proceed to configure the client’s endpoint if necessary. .. _linux-installation: Linux Installation ^^^^^^^^^^^^^^^^^^ - :ref:`ubuntu-installation` - :ref:`centos-stream-installation` .. _ubuntu-installation: ===================== Ubuntu Installation ===================== Install the ``.deb`` package with the system’s package manager: .. code:: shell sudo apt install bowtie*.deb Alternatively, if you have configured the Ubuntu Software Center to handle the ``.deb`` file type, double click on the ``.deb`` file to install. Once the package has installed, a window will open to accept initial configuration and a field for a remote Controller endpoint. Proceed to :ref:`client-configuration` to continue. .. admonition:: Ubuntu 20.04 User Services :class: Note Earlier versions of Ubuntu like 20.04 may not start user services correctly after installation. To start these services manually, use the terminal command:: bowtie-ctl enable .. _centos-stream-installation: ============================ CentOS Stream Installation ============================ After installing any :ref:`dependencies `, install the ``.rpm`` package downloaded from https://api.bowtie.works/platforms/CentOS-Stream: .. code:: shell sudo dnf install bowtie*.rpm Following package installation, reload ``systemd`` to refresh unit information: .. code:: shell sudo systemctl daemon-reload Finally, enable and start the Bowtie client daemons: .. code:: shell sudo systemctl enable --now bowtie-{service,dns} systemctl --user enable --now bowtie-gtk Once the package has installed, a window will open to accept initial configuration and a field for a remote Controller endpoint. Alternate configuration methods are to use :ref:`pre-configured packages ` or use the manual configuration method outlined in :ref:`client-connect`. After using any of those methods to configure your Controller endpoint, proceed to :ref:`accept-client`. .. _client-configuration: Client Configuration ==================== .. admonition:: Pre-configured packages :class: Note Clients using :ref:`pre-configured packages ` do not require manual configuration, and the installation process will skip these remaining steps. After :ref:`installing the client software `, a new window will open to accept an initial remote Controller endpoint: .. image:: _static/windows-config.png :scale: 40% :align: center Enter the URL for your organization’s Controller. This should match the ``https`` endpoint configured during the steps outlined in :doc:`setup-controller`. Click *Connect* to proceed to :ref:`login-client` to the Controller. .. _login-client: Log In ------ After connecting to the Controller endpoint, a new browser window should open to an authentication page to your organization’s Controller. This may be a single sign-on page, in which case the browser page will reflect your organization’s chosen single sign-on provider, or a basic login screen such as the following: .. image:: _static/windows-login.png :scale: 30% :align: center Log in with either your credentials for your organization’s single sign-on provider or the basic username and password provided by your administrator for the Bowtie Controller control plane. Authentication is necessary for associating users with devices and any policies reliant on user identity require authentication. After logging in, you may close the login page that subsequently appears: .. image:: _static/windows-authenticated.png :scale: 40% :align: center The Bowtie client configuration window will wait until the device has been :ref:`accepted ` if it hasn't been already: .. image:: _static/windows-waiting.png :scale: 40% :align: center A user with an administrative role on the Controller should proceed to :ref:`accept the new device `. .. admonition:: Additional Client Configuration :class: hint The steps outlined here apply for new, desktop-oriented client installations. For alternative configuration methods, including defining an initial Controller endpoint via configuration file, see :ref:`client-connect`. .. _accept-client: Accepting the Bowtie Client Device ---------------------------------- Before a Bowtie Client device may access the Bowtie network, the device must be authorized and the user must :ref:`login-client`. Authorization of a Client device may be :ref:`done in advance ` by an administrator or after the machine makes its initial connection: .. _approve-after: Authorization After Initial Connect ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ To authorize a device after its initial connection to the network, visit the :ref:`org-devices` tab in the Controller’s :ref:`Administrative Control Plane interface `. The name and serial number of the new device along with the last access time should appear in the Devices list. Once you have verified that this is the device you wish to authorize, click the ``Accept`` button: .. image:: _static/accept-device.png .. admonition:: Devices Page :class: tip The address for this administrative web page for a controller is set up in :ref:`endpoint` and this endpoint will also appear in the device's ``bowtie-service`` logs -- the steps for viewing logs are outlined in :ref:`client-logs` for each supported operating system. .. _approve-pre: Pre-Authorizing Devices ^^^^^^^^^^^^^^^^^^^^^^^ Alternatively, device serial numbers may be entered beforehand by an administrator so that connecting Clients are immediately granted access after connecting. See :ref:`pre-approval` for additional documentation. Next Steps ========== Once you've logged in, setup is complete! You may continue to use your network device as normal, but the addition of a Bowtie Client installation should now permit you to access network resources that you (or a Bowtie administrator) has granted to you and other members of the network. No ongoing maintenance or additional configuration changes should be necessary during the operation of the Bowtie Client. Any policy or network changes updated from the Bowtie :ref:`control-plane` will propagate to your device without manual steps and the service should persist across reboots and system shutdowns. - If you’re a Bowtie administrator or otherwise operating a Controller, you may proceed to :doc:`operating/controller` in order to continue on to define network policies and manage client devices. - If you’re a Bowtie user, it’s likely that you have no further need to interact with Bowtie directly any further. You may wish to leverage your new connection to your organization’s Bowtie installation to browse network resources that you may have newly-gained access to. Advanced users may optionally read :ref:`client-advanced` if you need more fine-grained control of the local Bowtie Client installation such as changing the behavior of DNS resolution.