machineid

README

machineid

Package machineid provides cross-platform generation of a stable machine identifier for Go applications.

The identifier is built from three pieces of information:

• SMBIOS hardware UUID – a value provided by the system firmware. Hypervisors typically generate a new SMBIOS UUID for cloned virtual machines, ensuring that each clone receives a different identifier.
• Operating system installation ID – the OS's own identifier when available. Examples include /etc/machine-id on Linux and the MachineGuid registry value on Windows. This acts as an additional safeguard and fallback.
• Operating system name – included to distinguish IDs when a machine is re-imaged with a different OS.

The final ID is the SHA-256 hash of the string os:<goos>|bios:<uuid>|inst:<id>. No MAC addresses or other volatile values are used, making the result stable even on modern macOS versions that randomise network interfaces on each reboot.

Usage

Install the module:

go get github.com/think0rcode/machineid

Then use it in your code:

package main

import (
    "fmt"

    "github.com/think0rcode/machineid"
)

func main() {
    id, err := machineid.ID()
    if err != nil {
        panic(err)
    }
    fmt.Println(id)
}

For troubleshooting, RawID exposes the underlying components:

bios, inst := machineid.RawID()
fmt.Println("bios:", bios, "install:", inst)

CLI debugging tool

A small helper at cmd/print prints the raw components and the hashed ID. It also supports logging and, on Windows, optional tool checks:

# Print values with debug logs
go run ./cmd/print --log-level debug

# On Windows, also check PowerShell and WMIC availability
go run ./cmd/print --check-tools

Supported platforms

• Linux – reads the SMBIOS UUID from /sys/class/dmi/id/product_uuid (falling back to /sys/devices/virtual/dmi/id/product_uuid) and the installation ID from /etc/machine-id or /var/lib/dbus/machine-id.
• macOS – obtains the hardware UUID from ioreg (falling back to system_profiler) and uses the system serial number as the installation ID, reusing the hardware UUID if unavailable.
• Windows – queries the SMBIOS UUID via PowerShell (prefers Get-CimInstance, falls back to Get-WmiObject, then wmic) and reads the installation ID from the MachineGuid registry value using the Go Windows registry API.

Releasing

1. Commit any pending changes and update documentation.

2. Create a new semantic version tag:

   git tag v0.1.0
   git push origin v0.1.0
   

   Go modules will pick up the latest tag automatically.

License

This project is licensed under the terms of the Apache License 2.0. See LICENSE.

Documentation

Overview

errors.go

Index

• Variables
• func ID() (string, error)
• func RawID() (biosUUID, installID string, biosErr, instErr error)
• func SetLogLevel(level LogLevel)
• func SetLogLevelFromEnv()
• type LogLevel

Variables

var ErrUnsupported = errors.New("machineid: unsupported platform")

ErrUnsupported indicates the current platform is not supported by the SMBIOS/installation ID backends.

Functions

func ID

func ID() (string, error)

ID returns a hashed identifier for the current machine. It combines the operating system name, SMBIOS hardware UUID, and an operating system installation identifier when available. The identifier is stable for a given machine yet changes when the VM or host is cloned.

func RawID

func RawID() (biosUUID, installID string, biosErr, instErr error)

RawID returns the unprocessed SMBIOS UUID and installation ID used to build the hashed identifier. It is primarily useful for diagnostics.

func SetLogLevel

func SetLogLevel(level LogLevel)

SetLogLevel configures the global log level for the machineid package. By default, logging is set to Error level to avoid noise in production.

func SetLogLevelFromEnv

func SetLogLevelFromEnv()

SetLogLevelFromEnv configures the log level from the MACHINEID_LOG_LEVEL environment variable. Valid values are: "error", "info", "debug" (case insensitive). If the environment variable is not set or invalid, defaults to Error level.

Types

type LogLevel

type LogLevel int

LogLevel represents the logging level for the machineid package

const (
	// LogLevelError shows only error messages
	LogLevelError LogLevel = iota
	// LogLevelInfo shows info and error messages
	LogLevelInfo
	// LogLevelDebug shows all messages including debug
	LogLevelDebug
)