AnywhereUSB Manager for Linux README

Linux Release 1.0
Manager 3.1.33.3

*******************************************************************************
* The AnywhereUSB Plus User Guide is online:

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



*******************************************************************************
* Installing vhci-hcd on RedHat or similar distros.

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

On Debian, Ubuntu and similar systems, the vhci_hcd kernel module is available
and just needs to be loaded at boot time.

Some distributions (e.g: RHEL/Rocky/AlmaLinux/CentOS) do not provide the
vhci-hcd kernel module. They are available in the kmod-usbip package from the
add-on El Repo (http://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.

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 yum install https://www.elrepo.org/elrepo-release-8.el8.elrepo.noarch.rpm
Note, the release version must match the release version of your OS release.
sudo yum --enablerepo=elrepo install kmod-usbip

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

The kernel module can be loaded by hand 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:

$ lsmod | grep vhci_hcd

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.

*******************************************************************************
* 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)

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.0-1.x86_64.rpm

*******************************************************************************
* After installation of the awusbmanager package, consider these next steps.
*******************************************************************************

1. The AnywhereUSB Manager typically runs as a non-root user. 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. The user must log out and log in
again to actually be in this group. 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 logs in.  So, while invoking the Manager immediately after running the above "usermod" command will appear to work, the user will not have permissions to manage AnywhereUSB until first logging out and then logging back in.

To see current group assignments of a user, run "groups <username>".


2. Headless

The awusbmanager-headless Manager is installed with the standard installers or it can be installed with a 64-bit headless only package. Once installed, it can be started with the following command:

$ awusbmanager-headless

Once running, it can be managed with the same cmdline commands documented for Windows and Linux Managers 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 USB devices on the PC.

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

$ awusbmanager-headless STOP



*******************************************************************************
* 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
awusb group:
    /etc/group

*******************************************************************************
* udev

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 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.

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

Typically you use apt or aptitude 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.

On RedHat and similar distributions (RHEL, 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 this release 1.0. The AnywhereUSB Manager works well
in Wayland in 2024. 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

*******************************************************************************
* 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

*******************************************************************************
* AnywhereUSB User Guide

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

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

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