AnywhereUSB Manager for Linux README

Linux Release 1.3
AnywhereUSB Manager version 3.1.39.4

*******************************************************************************

* The AnywhereUSB Plus Getting Started Guide

See the AnywhereUSB Plus Getting Started Guide for a walkthrough and step
by step procedure to get started with AnywhereUSB.

https://www.digi.com/anywhereusbplus/start

* AnywhereUSB Plus User Guide

See the AnywhereUSB Plus User Guide for AnywhereUSB Manager operation, Hub
administration, and headless operation.

https://www.digi.com/anywhereusbmanager/start

*******************************************************************************
* After installation of the awusbmanager package:
*******************************************************************************

See additional details for each of these items.

1. After installation, reboot linux PC.
   PC must be rebooted after installation to place user in awusb group.
2. vhci-hcd kernel module
   Needed for AnywhereUSB Manager operation, must be installed separately on
   RPM distros.
3. udev rules
   Rules for udev are installed by the package to load vhci-hcd properly.
4. systemd: awusbmanager.service
   Service script installed in systemd directory for starting of
   awusbmanager-headless at boot.
5. awusbmanager-headless
   Headless Manager supports VMs or servers without a display manager.
   Also desirable when commandline management is preferred (scripting).

*******************************************************************************

1. Digi recommends rebooting the linux PC after installing the
awusbmanager.  The udev daemon, vhci-hcd kernel module and user groups
all need to be configured and loaded correctly for AnywhereUSB to
operate properly.  See the sections below about udev and vhci-hcd.

The AnywhereUSB Manager typically runs as a non-root user in both standalone
and headless mode.  The non-root user must be in the awusb group.
The installer configures the user that installs the awusbmanager package
to be in this group.

After installation, the user session is not actually in the awusb group.
For most distros, a reboot of the linux PC is necessary for the user session
to be in this group.

NOTE: Digi recommends installing the awusbmanager package, installing the
vhci-hcd kernel module for RPM distros and then rebooting.

If other users on the PC would like to run the Manager to manage AnywhereUSB,
they must also be added to the awusb group.

o  Add additional users to awusb group if necessary

sudo usermod -a -G awusb <username>

where "<username>" should be replaced with the name of a user who will run the
Manager to manage AnywhereUSB.

NOTE: Changes to a user's group membership do not take effect until the next
time the user completely logs out and then logs in.  So, while invoking the
Manager immediately after running the above "usermod" command may appear to
work, the user will not have permissions to manage AnywhereUSB until first
logging out completely and then logging back in. In some windowing environments
the users session may be cached, and rebooting the box may be the most reliable
method, which is why reboot is always recommended.

To see group assignments of the current user session, run "groups".
To see group assignments of a user on next login, run "groups <username>".


*******************************************************************************

2. vhci-hcd

The AnywhereUSB Manager requires the vhci-hcd kernel module and the module's
configuration determines how many virtual USB devices your linux PC can
support concurrently.

a. On Debian, Ubuntu and similar distros, the vhci-hcd kernel module
that matches the running kernel is typically available in /lib/modules.
The package install attempts to load the kernel module and configure it to
be started at boot. You can see if it is available with the commands below.

b. Install on RedHat/Rocky/AlmaLinux or similar distros.

RPM distributions (RHEL/Rocky/AlmaLinux/CentOS) do not provide the vhci-hcd
kernel module. For these distros, it is typically available from the add-on
El Repo (See https://elrepo.org) repository. El Repo is a repository of prebuilt
packages for RedHat Enterprise Linux-style distributions. There are alternate
kernels, other optional packages, and kernel modules in El Repo. The kernel
module package that is needed by AnywhereUSB is called kmod-usbip.

c. Similarly, Oracle provides a repository of packages for Oracle Linux
distributions.  See https://yum.oracle.com/ to get started. You likely need the
kernel-uek-modules-extra package that matches your distribution to provide the
necessary kernel modules for AnywhereUSB.


To verify that the needed kernel modules are not already available on your
system:

$ modinfo vhci-hcd

modinfo: ERROR: Module vhci-hcd not found.

This means they must be installed manually. You can install the El Repo
versions with:

$ sudo rpm --import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
$ sudo rpm --import https://www.elrepo.org/RPM-GPG-KEY-v2-elrepo.org
Note, the release version must match the release version of your OS release.
Example, for EL8:
$ sudo yum install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm
Example, for EL9:
$ sudo yum install https://www.elrepo.org/elrepo-release-9.el9.elrepo.noarch.rpm

Install the kmod-usbip package containing the vhci-hcd kernel module:
$ sudo yum --enablerepo=elrepo install kmod-usbip

See https://elrepo.org/ for more information on El Repo and these commands.

Sometimes elrepo doesn't have a matching kmod-usbip and yum won't pick one to
install. The best approach is to boot a kernel version that does have a
matching kmod-usbip package, searching for an RPM on elrepo.org may help.

One workaround is to choose the kernel-lt from elrepo and the matching
kmod-usbip. Another is to ask yum to install the closest one elrepo has
available:

$ sudo yum --enablerepo=elrepo install --nobest kmod-usbip

If it does not exactly match the kernel, this kmod may not load with secure
boot enabled.


Oracle Linux kernel-uek-modules-extra packages can be downloaded and then
installed with yum install:

$ sudo yum install ./DOWNLOADED_PACKAGE.rpm

After the install, re-running the above modinfo command should confirm the
presence of the vhci-hcd kernel module.

The kernel module can be loaded by hand if necessary with this command:

$ sudo modprobe vhci-hcd

The install of the package adds this module name to /etc/modules so that it
will be loaded at boot time and loads the module during the install if
available.

You can see if the kernel module is successfully loaded.
NOTE: Need _ (underscore) for this command:

$ lsmod | grep vhci_hcd


*******************************************************************************

3. udev rules

When the DEB or RPM package is installed, udev rules are automatically
written to /etc/udev/rules.d/70-awusb.rules to ensure suitable access for
users in the awusb group to run the Manager and connect and disconnect USB
devices to/from the PC. Users do not need to be in the awusb group to USE the
USB devices connected to the PC via AnywhereUSB.

If these rules are not installed properly or do not match the distribution,
then the vhci-hcd files will not be set to the proper permissions for the
Manager to use them.  The Manager will report any installation issues in a
message box when it starts, or in the log for headless operation.  Being able
to connect to a Group but not to devices may also indicate that these rules are
not working. Similarly, connecting to a group, and having devices in that
group disappear and reappear repeatedly may also indicate that the rules
did not operate properly at boot.

The vhci-hcd files are in /sys/devices/platform/vhci_hcd.0/ on most distros.
The udev rules must match the vhci-hcd kernel module. An alternate version
of udev rules is available in /usr/share/doc/awusbmanager/. If the installed
udev rules are not working, replacing them with the alternate file may work.

Running the Manager as root is supported but not preferred for layered security
reasons. In this case the udev rules are not needed.

At start, the Manager will report configuration issues in a popup box or in
the Manager log.

*******************************************************************************

4. systemd

The awusbmanager.service file is installed by the install of either package.
Running the AnywhereUSB Manager as a service allows the PC to provide USB
devices from boot, instead of only when a user is logged in and running the
standalone Manager.

If the standard awusbmanager package is installed, both the awusbmanager and
awusbmanager-headless binaries are installed in /usr/bin, and the service file
is installed but the service will not be enabled and not be started. See the
commands below if you want to start it.

If the awusbmanager-headless package is installed, the awusbmanager service is
enabled to be started on next boot for DEB packages.  It will only be started
if the installing user is already a member of the awusb group, as in an upgrade
from an older awusbmanager package.

For the RPM packages, following Fedora policy. services do not start by
default.  The service will only be started by the install if a preset for the
service allows it.

To start the headless Manager at boot, you can run the following commands to
enable it for future sessions and start it:

$ sudo systemctl enable awusbmanager
$ sudo systemctl start awusbmanager

To stop the service in this session:

$ sudo systemctl stop awusbmanager

To disable the service for future sessions:

$ sudo systemctl disable awusbmanager

You can create a preset for the awusbmanager.service:

# echo 'enable awusbmanager.service' >/usr/lib/system/system-preset/70-awusbmanager.preset
# systemctl daemon-reload

Please see systemd documentation for more information.
$ man systemd
or
https://systemd.io/


*******************************************************************************

5. Headless operation

The awusbmanager-headless Manager binary is installed with the standard
installers or it can be installed with a 64-bit headless only package. It can
run without a display subsystem, such as on a server, and it can also be
used on any linux PC instead of the GUI Manager.

Once installed, it can be started with systemd, see previous section, or
manually with the following command:

$ awusbmanager-headless

Once running, it can be managed with the AnywhereUSB Manager awusbmanager
or awusbmanager-headless binary and the same cmdline commands documented
in the online AnywhereUSB User Guide. See the HELP cmd to get started:

$ awusbmanager-headless HELP

Common commands are LIST and CONNECT GROUP.

Either binary can be the running AnywhereUSB Manager, and either binary can be
used to control it. Once any one Manager is started, it will be the one that
connects and disconnects Groups and USB devices. Any user can use the connected
USB devices if they have appropriate system permissions to access them. These
users do not need to be in the awusb group unless they need to run the Manager
to manage AnywhereUSB on the PC.

To stop the running Manager window, chose File->Exit. To stop the headless
Manager, send the STOP command from another Manager invocation:

$ awusbmanager-headless STOP

If systemd has started the Manager, you will need to ask it to stop the Manager:

$ sudo systemctl stop awusbmanager

See the previous systemd section.



*******************************************************************************
* Technical details (things about Manager operation or installer):
*******************************************************************************
* File Locations after Installation

The following files or file locations will be found after installing the
Manager package:
Binaries:
    /usr/bin/awusbmanager
    /usr/bin/awusbmanager-headless
Documentation:
    /usr/share/doc/awusbmanager/
udev:
    /etc/udev/rules.d/70-awusb.rules
systemd:
    /usr/lib/systemd/system/awusbmanager.service
awusb group:
    /etc/group
sys:
    /sys/devices/platform/vhci_hcd*/
AnywhereUSB:
    ~/.AnywhereUSB/

*******************************************************************************
* Upgrading/downgrading

Typically you use apt, apt-get or dpkg on Debian-derived systems (Debian,
Ubuntu, Kubuntu, Lubuntu, Xubuntu, Mint) to install one of the DEB packages.
dpkg is usually able to upgrade packages without problems. Digi
recommends removing the package before a downgrade to before version 1.0.

On RedHat and similar distributions (RHEL, Oracle Linux, CentOS, openSUSE,
Fedora, Rocky, AlmaLinux), install one of the RPM packages with dnf or yum or
zypper.

NOTE: it is also possible to install using "rpm -i" and remove using "rpm -e"
but if you subsequently update to a different package version (say updating
from version 1.1 to 1.2), it will then be your responsibility to first
manually remove the deprecated version.  In contrast, dnf (and yum and zypper)
are smart enough to recognize when you are installing a changed version of
an already installed package, in which case it tells you if it's upgrading
(the version string of the candidate package is newer than the currently
installed package) or downgrading (the version string of the candidate
package is older than the currently installed package), and it removes
the previously installed version.

Once you have installed one of the awusbmanager packages, upgrades and
downgrades usually work, if not, you can uninstall and install the one you
want.

If you want to switch from a standard awusbmanager package to an
awusbmanager-headless package or vice versa, you can install the other and it
will replace the currently installed package.

*******************************************************************************
* Wayland and x11/Xorg

Wayland support is new in release 1.0. The AnywhereUSB Manager works well in
Wayland in 2024 and newer distro version. If issues are encountered, the
Manager can be run in x11 mode as well.

Option 1: Switch desktop to x11

Most distros have an option on the login screen to select x11/Xorg or Wayland.
Logging out, selecting x11 or Xorg and logging back in may resolve some issues.

Option 2: Run Manager in x11 mode on Wayland

The Manager can be run to use x11 libraries:

$ GDK_BACKEND=x11 awusbmanager

The current session mode can be determined with the Manager About Box, which
shows the current X Session and Desktop.

*******************************************************************************
* Manager does not exit when choosing the Close or X on main Window by design

When you close the Manager, it does not exit so it can keep USB devices
connected and available to all users on your PC. The Manager remains in the
taskbar and/or application panel. If you want to exit the Manager (and your
AnywhereUSB devices will be disconnected), use File->Exit.
The Manager will also exit if you send it an EXIT commandline cmd.

$ awusbmanager EXIT

Note that if systemd has started the awusbmanager, you will need to stop it
using systemd, see the previous systemd section.

*******************************************************************************
* If AnywhereUSB Manager does not find local AnywhereUSB Hubs

Sometimes the Manager cannot find AnywhereUSB Hubs with Autofind.
The Manager uses mDNS queries to locate AnywhereUSB Hubs which must be on the
same network segment to be found. Routers and NAT block mDNS query responses.

Check that Autofind Hubs is enabled in File->Preferences.
Check if a firewall is blocking mDNS traffic.
mDNS uses standard unicast UDP frames and multicast addresses 224.0.0.251,
FF02::FB using UDP port 5353.

Digi recommends adding Hubs by IP address to the Known Hubs list with
Configure->Known Hubs and then disabling Autofind in production deployments.
Hubs can be easily added to the Known Hubs list with the Hub menu item:
Add to Known Hubs

*******************************************************************************

If you need more virtual USB devices on a single linux PC, the kernel can be
rebuilt with a modified configuration that includes these modified
configuration items in 4.13 or newer kernels.

CONFIG_USBIP_VHCI_HC_PORTS=8
CONFIG_USBIP_VHCI_NR_HCS=8

Recompiling a linux kernel is an advanced procedure, please consult a linux
expert for assistance. It also requires continual kernel updates manually to
receive security updates that affect the kernel. In addition, secure boot or
signed distros may refuse to load unsigned kernels and kernel modules built
by hand.

Recent Debian releases offer more than 8 USB devices, most other distributions
(RedHat, Ubuntu) do not.

*******************************************************************************
* Warning on apt installs of DEB packages

Sometimes DEB package managers will report this notice. The package is
installed properly and the notice can be ignored.

N: Download is performed unsandboxed as root as file 'awusbmanager_1.0_amd64.deb' couldn't be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)

Here is a possible workaround:
$ sudo chown _apt:root /var/lib/update-notifier/package-data-downloads/partial
$ sudo chmod 700 /var/lib/update-notifier/package-data-downloads/partial

For more information:
https://askubuntu.com/questions/908800/what-does-this-apt-error-message-download-is-performed-unsandboxed-as-root

*******************************************************************************
* Warning on zypper installs of RPM packages
*******************************************************************************

The RPM packages are distributed unsigned.  If zypper complains about
an unsigned package or header, either select 'i' to ignore the warning
or explicitly use the --allow-unsigned-rpm option, e.g:

$ sudo zypper install --allow-unsigned-rpm  ./awusbmanager-1.3-1.x86_64.rpm

*******************************************************************************

* The AnywhereUSB Plus Getting Started Guide

See the AnywhereUSB Plus Getting Started Guide for a walkthrough and step
by step procedure to get started with AnywhereUSB.

https://www.digi.com/anywhereusbplus/start

* AnywhereUSB Plus User Guide

See the AnywhereUSB Plus User Guide for AnywhereUSB Manager operation, Hub
administration, and headless operation.

https://www.digi.com/anywhereusbmanager/start

*******************************************************************************
*END***************************************************************************
