Skip to content

Distribution Detection

The distro script detects the operating system, kernel, architecture, distribution, version, virtualisation platform, and container type of a monitored host. It has no additional runtime dependencies and works in any sh-compatible environment, including ksh and bash.

Supported platforms

The script supports:

  • Linux
  • FreeBSD, OpenBSD, NetBSD, and DragonFly BSD
  • Cygwin and MinGW
  • QNX
  • AIX
  • HP-UX
  • Solaris and SunOS
  • Hurd
  • Minix
  • VxWorks
  • macOS

Supported Linux distributions include Debian, Ubuntu, Red Hat, CentOS, Fedora, Amazon Linux, openSUSE, SuSE, Arch Linux, Gentoo, Mageia, Slackware, Armbian, DietPi, OpenWrt, IPFire, Synology, Unraid, Mandriva, Mandrake, Knoppix, Linux From Scratch, Photon, Annvix, Arklinux, Aurox, BlackCat, Cobalt, Conectiva, FreeEOS, HLFS, Immunix, Linux-PPC, MkLinux, Novell Linux Desktop, PLD, Rubix, SME Server, Tiny Sofa, Trustix, TurboLinux, UltraPenguin, UnitedLinux, VA-Linux, Yellow Dog, and MailCleaner. Any distribution with an /etc/os-release file should also be detected automatically.

Recognised BSD distributions include pfSense, OPNsense, HardenedBSD, FreeNAS, and PC-BSD.

The script can detect VMware, Xen (HVM/PV), Microsoft Hyper-V, Parallels, KVM, QEMU, Oracle VirtualBox, bhyve, Amazon EC2, and browser-based x86 emulators (browservm). It can also identify Docker, LXC, OpenVZ, and FreeBSD Jail containers.

Run without installing

Run the latest version directly without saving it to the local system:

Bash
1
curl -Ls https://www.observium.org/files/distro | sh

Alternatively, use wget:

Bash
1
wget -qO- https://www.observium.org/files/distro | sh

Installation

Download the latest script to the device that will be monitored:

Bash
1
2
sudo curl -fLo /usr/local/bin/distro https://www.observium.org/files/distro
sudo chmod +x /usr/local/bin/distro

Alternatively, use wget:

Bash
1
2
sudo wget -O /usr/local/bin/distro https://www.observium.org/files/distro
sudo chmod +x /usr/local/bin/distro

Verify the installation:

Bash
1
/usr/local/bin/distro

The default output is pipe-delimited and contains seven fields:

Text Only
1
OS|KERNEL|ARCH|DISTRO|VERSION|VIRT|CONT

For example:

Text Only
1
Linux|5.15.0-91-generic|amd64|Ubuntu|22.04.5||

Updating an existing installation

An installed copy can update itself to the latest version:

Bash
1
sudo /usr/local/bin/distro -u

The update requires mktemp and either curl or wget. It preserves the installed file's permissions, validates the downloaded script, and replaces the current file only after a successful download. Run the command as a user with permission to replace the installed file.

Alternatively, download the latest version over the installed script and verify its version:

Bash
1
2
3
sudo curl -fLo /usr/local/bin/distro https://www.observium.org/files/distro
sudo chmod +x /usr/local/bin/distro
/usr/local/bin/distro -v

Or with wget:

Bash
1
2
3
sudo wget -O /usr/local/bin/distro https://www.observium.org/files/distro
sudo chmod +x /usr/local/bin/distro
/usr/local/bin/distro -v

Command-line usage

Text Only
1
Usage: distro [-f format] [-o out] [-h] [-u] [-v]

Options:

  • -f <format> - output format: pipe (default), twopipe, json, ini, or export
  • -o <out> - show only one value: os, kernel, arch, distro, version, virt, or cont
  • -h - show help
  • -u - update the installed script to the latest version
  • -v - show the script version

Examples:

Bash
1
2
3
4
/usr/local/bin/distro
/usr/local/bin/distro -f json
/usr/local/bin/distro -o virt
DISTROFORMAT=export /usr/local/bin/distro

The ini, export, and json formats also include the script version as SCRIPTVER or scriptver.

Using the script from another application

Set DISTROEXEC before sourcing the script to prevent it from running automatically:

Bash
1
2
3
4
5
6
DISTROEXEC=1
. /usr/local/bin/distro
getos
getdistro
getversion
echo "$DISTRO $VERSION"

The script provides these variables:

  • OS - operating system, for example Linux, Solaris, or FreeBSD
  • KERNEL - kernel version or name
  • ARCH - architecture, for example amd64 or i386
  • DISTRO - distribution name, for example Debian, OpenIndiana, or pfSense
  • VERSION - distribution version, or OS version when DISTRO is empty
  • VIRT - virtualisation technology, when detected
  • CONT - container technology, when detected
  • DISTROSCRIPT - script version

Sourcing the script alone does not populate or export these values. Call the corresponding function first: getos, getkernel, getarch, getdistro, getversion, getvirt, or getcont.

If a value is unavailable or not applicable, it is left blank. On a generic FreeBSD or OpenBSD installation, DISTRO is blank and VERSION contains the kernel name. The script normalises x86_64 to amd64 and ix86 to i386. Virtualisation and container names generally follow the systemd-detect-virt naming convention.

Net-SNMP integration

Add the following line to /etc/snmp/snmpd.conf on the device to be monitored:

Text Only
1
extend distro /usr/local/bin/distro

Without a custom OID prefix, Net-SNMP exposes the result through the standard NET-SNMP-EXTEND-MIB. Observium reads nsExtendOutput1Line."distro", whose numeric OID is:

Text Only
1
.1.3.6.1.4.1.8072.1.3.2.3.1.1.6.100.105.115.116.114.111

Existing installations using the legacy UCD-SNMP OID continue to be supported. If an older Net-SNMP version does not support extend, use this legacy exec configuration:

Text Only
1
exec .1.3.6.1.4.1.2021.7890.1 distro /usr/local/bin/distro

Restart the SNMP daemon:

Bash
1
sudo service snmpd restart

Testing via SNMP

Walk the standard Net-SNMP extend tree from the Observium server:

Bash
1
snmpwalk -v2c -c <community> <hostname> .1.3.6.1.4.1.8072.1.3.2

The output should include nsExtendOutput1Line."distro" with the same seven pipe-delimited fields returned when the script is run locally, for example:

Text Only
1
NET-SNMP-EXTEND-MIB::nsExtendOutput1Line."distro" = STRING: Linux|5.15.0-91-generic|amd64|Ubuntu|22.04.5||

Testing legacy configurations

Older installations may use extend with the Observium UCD-SNMP OID prefix:

Text Only
1
extend .1.3.6.1.4.1.2021.7890.1 distro /usr/local/bin/distro

Check the exact output OID used by Observium:

Bash
1
snmpget -v2c -c <community> <hostname> .1.3.6.1.4.1.2021.7890.1.3.1.1.6.100.105.115.116.114.111

Installations using the legacy exec configuration can be checked separately:

Bash
1
snmpget -v2c -c <community> <hostname> .1.3.6.1.4.1.2021.7890.1.101.1

Both commands should return the pipe-delimited distro value. For example:

Text Only
1
Linux|5.15.0-91-generic|amd64|Ubuntu|22.04.5||

If the configuration type is unknown, walk the complete legacy subtree and look for either of the OIDs above:

Bash
1
snmpwalk -v2c -c <community> <hostname> .1.3.6.1.4.1.2021.7890.1