Go bindings to systemd socket activation, journal, D-Bus, and unit files

Overview

go-systemd

godoc minimum golang 1.12

Go bindings to systemd. The project has several packages:

  • activation - for writing and using socket activation from Go
  • daemon - for notifying systemd of service status changes
  • dbus - for starting/stopping/inspecting running services and units
  • journal - for writing to systemd's logging service, journald
  • sdjournal - for reading from journald by wrapping its C API
  • login1 - for integration with the systemd logind API
  • machine1 - for registering machines/containers with systemd
  • unit - for (de)serialization and comparison of unit files

Socket Activation

An example HTTP server using socket activation can be quickly set up by following this README on a Linux machine running systemd:

https://github.com/coreos/go-systemd/tree/main/examples/activation/httpserver

systemd Service Notification

The daemon package is an implementation of the sd_notify protocol. It can be used to inform systemd of service start-up completion, watchdog events, and other status changes.

D-Bus

The dbus package connects to the systemd D-Bus API and lets you start, stop and introspect systemd units. API documentation is available online.

Debugging

Create /etc/dbus-1/system-local.conf that looks like this:

<!DOCTYPE busconfig PUBLIC
"-//freedesktop//DTD D-Bus Bus Configuration 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
<busconfig>
    <policy user="root">
        <allow eavesdrop="true"/>
        <allow eavesdrop="true" send_destination="*"/>
    </policy>
</busconfig>

Journal

Writing to the Journal

Using the pure-Go journal package you can submit journal entries directly to systemd's journal, taking advantage of features like indexed key/value pairs for each log entry.

Reading from the Journal

The sdjournal package provides read access to the journal by wrapping around journald's native C API; consequently it requires cgo and the journal headers to be available.

logind

The login1 package provides functions to integrate with the systemd logind API.

machined

The machine1 package allows interaction with the systemd machined D-Bus API.

Units

The unit package provides various functions for working with systemd unit files.

Issues
  • daemon: improve SdNotify errors signaling

    daemon: improve SdNotify errors signaling

    This patch makes SdNotify return value compliant to the sd_notify() documentation. See sd_notify(3) man page.

    Fixes: https://github.com/coreos/go-systemd/issues/184

    opened by alepuccetti 29
  • dbus: Fix API break from godbus

    dbus: Fix API break from godbus

    Something in godbus seems to have broken API, thus breaking builds including go get. This patches fixes those changes. I don't know any background about this change, so if anyone has information, I'd sure like to know! Thanks

    opened by purpleidea 24
  • sdjournal: dlopen libsystemd instead of linking against it

    sdjournal: dlopen libsystemd instead of linking against it

    This allows not having to link users of the library to libsystemd, detect at runtime if it exists or not and react accordingly.

    Also, refactor dlopen code.

    kind/friction component/journal 
    opened by iaguis 24
  • sdjournal: add GetEntry method to retrieve all fields

    sdjournal: add GetEntry method to retrieve all fields

    Implements the same semantics as the JOURNAL_FOREACH_DATA_RETVAL macro in journal-internal.h and produces a *JournalEntry with every field with its corresponding data in a map[string]string. Also it includes address fields like realtime (__REALTIME_TIMESTAMP), monotonic (__MONOTONIC_TIMESTAMP and cursor (__CURSOR).

    It mimics more or less journalctl -o json.

    Fixes #142 Supersedes #136

    kind/enhancement component/journal 
    opened by glerchundi 22
  • dbus: add support for new ListUnits* methods

    dbus: add support for new ListUnits* methods

    …d support)

    is a part of this change: https://github.com/endocode/systemd/commit/5b4452a643d924015ed25972d071ad8802aad29c and this pull request: https://github.com/coreos/fleet/pull/1564

    opened by kayrus 19
  • Add go module support

    Add go module support

    This PR adds a go.mod and go.sum to the project which contains the latest dependencies. It would be awesome if we could tag a release according to semver after this PR got merged, WDYT? :innocent:

    opened by saschagrunert 16
  • activation: close files after creating listeners

    activation: close files after creating listeners

    This is an adaptation of #215 to ensure tests don't fail and extend the behaviour to PacketConns(). A bit of test coverage is lost, but just testing if variable environments are not unset in the simple case doesn't seem worth adding more code.

    Fix #215

    kind/bugfix 
    opened by vincentbernat 16
  • journal: use a connection-less socket

    journal: use a connection-less socket

    When a non temporary error is detected while sending a message, the connection should be closed to attempt a reconnection, otherwise it won't be possible to send new messages to journald anymore.

    opened by cbonte 15
  • sdjournal: fix return values type

    sdjournal: fix return values type

    fix inconsistency in return types for journal functions: NextSkip, Previous, PreviousSkip. Currently they will return (uint64, error), however according to sd-journal.h it should be (int, error)

    Journal.Next returns (int, error) Journal.Previous returns (uint64, error)

    https://github.com/systemd/systemd/blob/master/src/systemd/sd-journal.h#L98

    opened by mnaboka 15
  • dbus: add PropPids to set initial pids of transient scope units

    dbus: add PropPids to set initial pids of transient scope units

    Should there also be a usage example on how to create a transient scope unit instead of a transient service unit?

    Feel free to use https://github.com/mgit-at/systemd-runas/blob/master/main.go as a example on how to use the call with transient scopes.

    component/dbus 
    opened by gebi 15
  • journal: use a connection-less socket

    journal: use a connection-less socket

    This gets rid of the connection ownership problem by using a non-connected Unix datagram socket and an explicit destination to send each message. It does not impact the public API, but it requires a minimum-go version bump due to https://go-review.googlesource.com/c/go/+/45872 (golang 1.10+).

    Fixes https://github.com/coreos/go-systemd/issues/5 Fixes https://github.com/coreos/go-systemd/issues/233 Fixes https://github.com/coreos/go-systemd/issues/275


    Note: as 1.11 got released, all upstream supported versions of the Go runtime have a fixed version of WriteMsgUnix that this PR uses. However, this means that the journal package won't work on older/buggy runtimes (<= 1.9).

    needs/review component/journal kind/bugfix 
    opened by lucab 14
  • Writing `UNIT` to journal

    Writing `UNIT` to journal

    I'm attempting to write a message to the journal using journal.Send(). I'd like to write this message for a specific service, so I've added vars as

    vars := map[string]string{
       "UNIT": "myservice.service",
    }
    err = journal.Send(message, journal.PriInfo, vars)
    

    I am seeing the log appear in the journal via journalctl -f, but it's appearing as main[12345] <message> when I was expecting the log entry to appear as myservice[12345] <message>. Likewise, I do not see the log via journalctl -f -u myservice. Am I missing something here or is the UNIT field (https://www.freedesktop.org/software/systemd/man/systemd.journal-fields.html) unsupported by this library? Thanks

    opened by ginglis13 0
  • Module for reading service credentials

    Module for reading service credentials

    I would like a module that can read credentials when the current program is running as a systemd service.

    This should be fairly simple and a small amount of code. I'm willing to send a PR at some point.

    opened by cedws 1
  • bug(dbus): New[User|System]ConnectionContext doesn't respect incoming context.Context

    bug(dbus): New[User|System]ConnectionContext doesn't respect incoming context.Context

    Hi Community, I a recent event, I just discovered that the two functions to establish dbus connection doesn't handle context deadline event

    func TestGoSystemd(t *testing.T) {
    	ctx, _ := context.WithTimeout(context.Background(), 0)
    	_, err := dbus.NewSystemConnectionContext(ctx)
    	if err != nil {
    		t.Fatal(err)
    	}
    }
    

    this throws:

    === RUN   TestGoSystemd
        dbus_test.go:13: read unix @->/run/dbus/system_bus_socket: use of closed network connection
    --- FAIL: TestGoSystemd (0.00s)
    

    Same for

    ctx, _ := context.WithTimeout(context.Background(), 0)
    _, err := dbus.NewUserConnectionContext(ctx)
    // : read unix @->/run/user/1000/bus: use of closed network connection
    

    And when integrated with large software, it makes debugging a lot harder. I think here it's best to use standard context.DeadlineExceeded error when such a scenario occurs. Thank you!

    opened by bisakhmondal 4
  • login1: Add NewWithConnection method

    login1: Add NewWithConnection method

    This method allows passing existing D-Bus connection, which allows to re-use connection between clients and to mock D-Bus connection for testing purposes.

    Extracted from #390 Includes commits from #395

    Signed-off-by: Mateusz Gozdek [email protected]

    opened by invidian 0
  • login1: Use blackbox testing

    login1: Use blackbox testing

    This is a desired way of testing to avoid creating fragile test suites and be able to refactor code without touching tests.

    Extracted from #390

    Signed-off-by: Mateusz Gozdek [email protected]

    opened by invidian 0
  • sdjournal: JournalReader.Follow is not thread-safe

    sdjournal: JournalReader.Follow is not thread-safe

    The "Thread safety" section of the sd-journal manpage says:

    Functions that operate on sd_journal objects are thread agnostic — given sd_journal pointer may only be used from one specific thread at all times (and it has to be the very same one during the entire lifetime of the object), but multiple, independent threads may use multiple, independent objects safely.

    That section was added to the documentation in systemd v232 (wayback machine).

    Code using sdjournal.Journal can abide by this constraint by e.g.:

    runtime.LockOSThread()
    j, err := sdjournal.NewJournal()
    // Use j exclusively from this goroutine
    

    On the other hand, func (*JournalReader) Follow cannot be used thread-safely as it calls Journal methods from spawned goroutines. https://github.com/coreos/go-systemd/blob/9ed442a88da2e6230e1d13be1820a5357055aec8/sdjournal/read.go#L232-L236

    opened by corhere 0
Releases(v22.3.2)
  • v22.3.2(May 10, 2021)

  • v22.3.1(Apr 1, 2021)

  • v22.3.0(Mar 19, 2021)

    Changes:

    • dbus: add KillUnitWithTarget
    • dbus: fix typo in GetUnitTypePropertyContext
    • sdjournal: drop conditional static specifier
    • ci: clean up legacy helpers
    • ci: let system settle before running tests
    Source code(tar.gz)
    Source code(zip)
  • v22.2.0(Mar 3, 2021)

    Changes:

    • go-systemd: fix building on windows
    • dbus: add context-aware methods
    • dbus: add context to open functions
    • dbus: add ListJobs method
    • sdjournal: SeekTail should be followed by Previous, not Next
    • sdjournal: add GetBootID support
    • ci: add initial GitHub workflow
    • ci: add container tests
    Source code(tar.gz)
    Source code(zip)
  • v22.1.0(Jun 2, 2020)

    Changes:

    • docs: update docs links in README
    • unit: do not export private constants
    • unit: deserialize keeps all semantic data
    • deserialize: Use quote to print possibly-invalid string
    • login1: support getting active session and session details
    Source code(tar.gz)
    Source code(zip)
  • v22.0.0(Nov 11, 2019)

    Breaking changes:

    • minimum Go toolchain version is now 1.12
    • switched to Go modules, removed dep support
    • switched to semver tags to appease Go mod
    Source code(tar.gz)
    Source code(zip)
  • v21(Nov 4, 2019)

  • v20(Jun 20, 2019)

    New features:

    • import1: implement importd methods
    • dbus: introduce GetAllProperties() for fetching all systemd unit properties
    • machine1: add CreateMachine call (and variations)

    Other changes in this release:

    • sdjournal: provide errno codes in error messages as strings
    Source code(tar.gz)
    Source code(zip)
  • v19(Mar 22, 2019)

    Breaking changes:

    • minimum Go toolchain version is now 1.10

    Other changes in this release:

    • journal: use a connection-less socket
    • docs: fix multiple docstrings
    • examples: Listeners method is now without arguments
    • examples: systemd-activate is now systemd-socket-activate
    • test/machine1: fix sporadic test failures from TestMachine
    • journal: skip sending test if journald is unavailable
    Source code(tar.gz)
    Source code(zip)
  • v18(Oct 31, 2018)

    Breaking changes:

    • minimum Go toolchain version is now 1.7

    New features:

    • machine1: add methods ListMachines, ListImages, GetMachineAddresses

    Other changes in this release:

    • dbus: Fix API break from godbus
    • unit: use ContainsAny instead of IndexAny
    • journal: fix validation of key names
    • docs: Add more detail to Conn.ListUnits
    • tests/activation: fix local test run
    • test/journal: add some send tests
    Source code(tar.gz)
    Source code(zip)
  • v17(May 11, 2018)

    Breaking changes:

    • activation: remove unsafe support for fd re-use (removed unsetEnv flags)

    New features:

    • activation: add two functions to provide listeners with names
    • daemon: add convenience constants for SdNotify
    • login1: add support for session management
    • sdjournal: add formatting feature to JournalReader

    Other changes in this release:

    • activation: close files after creating listeners
    • daemon: clean up copyright headers and documentation
    • dbus: add systemd requirement note to ListUnitsByNames
    • journal: add missing error handling for write & unlink calls
    • sdjournal: add docstrings for public error values
    • sdjournal: fix race conditions in JournalReader.Follow
    • sdjournal: fix concurrency & shadowing issues in tests
    • sdjournal: propagate AddMatch errors in constructor
    • ... and many more linting fixes (thanks @muesli!)
    Source code(tar.gz)
    Source code(zip)
  • v16(Feb 2, 2018)

    Summary of changes in this release:

    • dbus: fix subStateSubscriber crash
    • dbus: make SetSubStateSubscriber safer
    • dbus: add SetPropertiesSubscriber method
    • dbus: add SystemState method for getting system state
    • login1: add close function
    • sdjournal: clarify documentation's notion of "current"
    • sdjournal: support testing cursor against current position
    Source code(tar.gz)
    Source code(zip)
  • v15(Jul 31, 2017)

    Summary of changes in this release:

    • util: fix runningFromSystemService
    • sdjournal: add NewJournalFromFiles
    • sdjournal: fix Wait() timeout
    • sdjournal: fix goroutine leak
    • sdjournal: add GetCatalog
    • machined: add several methods
    • tests: misc improvements
    Source code(tar.gz)
    Source code(zip)
  • v14(Nov 14, 2016)

    Breaking changes:

    • daemon: introduce support for cleaning env variables
      (boolean parameter added to SdNotify and SdWatchdogEnabled)

    Other changes in this release:

    • daemon: add watchdog checker
    • dbus: make New() fall back to direct systemd connection
    • util: add tests for util package
    • test: add license header check
    Source code(tar.gz)
    Source code(zip)
  • v13(Oct 24, 2016)

    Summary of changes in this release:

    • dbus: add additional tests for dbus methods
    • sdjournal: add GetUniqueValues
    • sdjournal: fix return values type
    • dbus/properties: add service type
    • doc: syntax highlight activation in README
    Source code(tar.gz)
    Source code(zip)
  • v12(Aug 26, 2016)

    Summary of changes in this release:

    • dbus: add mask/unmask for unit files
    • dbus: add PropPids to set initial pids of transient scope units
    • util: conditionally build CGO functions
    • activation: don't specify NextProtos so that we can take advantage of HTTP/2
    • sdjournal: fix concurrent map access
    • sdjournal: fix race condition in test
    • sdjournal: fix memory leak in cursor handling
    Source code(tar.gz)
    Source code(zip)
  • v11(Jul 22, 2016)

    Breaking changes:

    • daemon: improve SdNotify errors signaling (changed return type)

    Other changes in this release:

    • sdjournal: fix an implicit seek to head
    • sdjournal: add GetDataBytes() and GetDataValueBytes() to Journal
    • multiple testsuite fixes
    Source code(tar.gz)
    Source code(zip)
  • v10(Jun 23, 2016)

    Summary of changes in this release:

    • sdjournal: fix incomplete reads in JournalReader.Read()
    • sdjournal: break the loop if error happens during Write()
    • sdjournal: fix Writer call
    Source code(tar.gz)
    Source code(zip)
  • v9(Jun 7, 2016)

    Summary of changes in this release:

    • dbus: add support for new ListUnits* methods
    • sdjournal: export all fields IDs
    • sdjournal: add GetEntry method to retrieve all fields
    • sdjournal: don't close libsystemd on Close()
    Source code(tar.gz)
    Source code(zip)
  • v8(May 26, 2016)

    Summary of changes in this release:

    • sdjournal: add support for cursors (get, seek, test)
    • sdjournal: export SYSLOG_IDENTIFIER
    • dbus: expose NewConnection method
    Source code(tar.gz)
    Source code(zip)
  • v7(May 24, 2016)

  • v6(May 19, 2016)

    Summary of changes in this release:

    • rewritten sdjournal to dlopen libsystemd instead of linking to it
    • examples are not built by default anymore, making go get happy
    • journal entry field _TRANSPORT is now exposed
    Source code(tar.gz)
    Source code(zip)
  • v5(Mar 21, 2016)

    This release adds a number of new methods for working with the journal and exposing more information about systemd, as well as a minor bugfix and small internal code cleanup.

    • Add several new functions to sdjournal: AddDisjunction, AddConjunction, GetDataValue, FlushMatches, SetDataThreshold
    • Add ability to load journal from custom directory (sdjournal.NewJournalFromDir)
    • Add GetManagerProperty to dbus to obtain systemd1.manager interface properties
    • Add several utility functions to detect information when invoked from systemd (GetRunningSlice, RunningFromSystemService, CurrentUnitName, GetMachineID)
    • Add login1.Inhibit and login1.Subscribe
    • Add dbus.ListUnitFiles
    • Correctly propagate error during sdjournal.AddMatch
    Source code(tar.gz)
    Source code(zip)
  • v4(Nov 5, 2015)

    • add dbus.NewSystemdConnection() for connecting directly to systemd.
    • add github.com/coreos/go-systemd/sdjournal package for low-level access to journal
    • add activation.TLSListeners for socket activation of TLS sockets
    • stable ordering of unit serialization
    Source code(tar.gz)
    Source code(zip)
  • v2(May 21, 2014)

Owner
CoreOS
Key components to secure, simplify and automate your container infrastructure
CoreOS
Git extension for versioning large files

Git Large File Storage Git LFS is a command line extension and specification for managing large files with Git. The client is written in Go, with pre-

Git LFS 10.4k Jun 23, 2022
JuiceFS is a distributed POSIX file system built on top of Redis and S3.

JuiceFS is a high-performance POSIX file system released under GNU Affero General Public License v3.0. It is specially optimized for the cloud-native

Juicedata, Inc 5.5k Jun 25, 2022
Go implementation of systemd Journal's native API for logging

journald Package journald offers Go implementation of systemd Journal's native API for logging. Key features are: based on a connection-less socket wo

Grigory Zubankov 30 Mar 4, 2022
Keygen SDK for Go. Integrate license activation and automatic updates for Go binaries.

Keygen Go SDK Package keygen allows Go programs to license and remotely update themselves using the keygen.sh service. Usage keygen.Validate(fingerpri

Keygen 45 Jun 10, 2022
Simple Relay between a Unix socket and a TCP socket, and vice versa.

Simple TCP <-> Unix Relay simpletcpunixrelay is a program which exposes a TCP endpoint as a Unix socket and vice versa. Usecase Let's say you are runn

Antoine Catton 0 Dec 4, 2021
Glue - Robust Go and Javascript Socket Library (Alternative to Socket.io)

Glue - Robust Go and Javascript Socket Library Glue is a real-time bidirectional socket library. It is a clean, robust and efficient alternative to so

DesertBit 402 May 25, 2022
Glue - Robust Go and Javascript Socket Library (Alternative to Socket.io)

Glue - Robust Go and Javascript Socket Library Glue is a real-time bidirectional socket library. It is a clean, robust and efficient alternative to so

DesertBit 402 May 25, 2022
go-socket.io is library an implementation of Socket.IO in Golang

go-socket.io is library an implementation of Socket.IO in Golang, which is a realtime application framework.

Googol Lee 4.7k Jun 25, 2022
GOWS is GoLang web-socket module Provides you with ease of handling web socket connections with a few lines

GOWS GOWS is GoLang web-socket module Provides you with ease of handling web socket connections with a few lines, it supports multi-connection on one

null 6 Apr 4, 2022
📔 Journal helps you manage multiple journals with ease from the comfort of your terminal, web browser or API client.

Journal helps you manage multiple journals with ease from the comfort of your terminal, web browser or API client. You can import/export journals as horcruxes and set simple customizations for layout, theme, and keybindings.

Paul Ebose 3 Aug 14, 2021
Go bindings for D-Bus

Documentation Look at the API on GoPkgDoc. Installation goinstall github.com/norisatir/go-dbus Usage Methods Methods is obtained with meth, err := co

nori satir 18 Oct 20, 2019
Native Go bindings for D-Bus

dbus dbus is a simple library that implements native Go client bindings for the D-Bus message bus system. Features Complete native implementation of t

null 717 Jun 22, 2022
Native Go bindings for D-Bus

go.dbus go.dbus is a simple library that implements native Go client bindings for the D-Bus message bus system. Features Complete native implementatio

Georg Reinke 121 Feb 19, 2022
Split multiple Kubernetes files into smaller files with ease. Split multi-YAML files into individual files.

Split multiple Kubernetes files into smaller files with ease. Split multi-YAML files into individual files.

Patrick D'appollonio 160 Jun 20, 2022
Split multiple Kubernetes files into smaller files with ease. Split multi-YAML files into individual files.

kubectl-slice: split Kubernetes YAMLs into files kubectl-slice is a neat tool that allows you to split a single multi-YAML Kubernetes manifest into mu

Patrick D'appollonio 161 Jun 22, 2022
🔊Minimalist message bus implementation for internal communication

?? Bus Bus is a minimalist event/message bus implementation for internal communication. It is heavily inspired from my event_bus package for Elixir la

Mustafa Turan 266 Jun 16, 2022
Go simple async message bus

?? message-bus Go simple async message bus. ?? ABOUT Contributors: Rafał Lorenz Want to contribute ? Feel free to send pull requests! Have problems, b

Rafał Lorenz 221 Jun 22, 2022
A lightweight transactional message bus on top of RabbitMQ

grabbit A lightweight transactional message bus on top of RabbitMQ supporting: Supported Messaging Styles One Way (Fire and forget) Publish/Subscribe

WeWork 85 Jun 2, 2022
Gin best practices, gin development scaffolding, too late to explain, get on the bus.

Table of Contents generated with DocToc gin_scaffold 现在开始 文件分层 log / redis / mysql / http.client 常用方法 swagger文档生成 gin_scaffold Gin best practices, gin

niuyufu 510 Jun 19, 2022
Easy to use distributed event bus similar to Kafka

chukcha Easy to use distributed event bus similar to Kafka. The event bus is designed to be used as a persistent intermediate storage buffer for any k

Yuriy Nasretdinov 71 Jun 8, 2022
simple golang event bus structure

super simple and small event bus structure for golang that allows emissions as go routines.

bfu4 5 Dec 11, 2021
Go-turing-i2c-cmdline - Controlling the i2c management bus of the turing pi with i2c works fine

go-turing-i2c-cmdline What is it? Controlling the i2c management bus of the turi

null 2 Jan 24, 2022
Govent is an event bus framework for DDD event source implement

Govent is an event bus framework for DDD event source implement. Govent can also solve the package circular dependency problem.

Michaelyn 2 Jan 28, 2022
Messagebus - Simple Message Bus Written in Golang

MessageBus Simple Message Bus Written in Golang How to Use go get gopkg.io/Usada

Usada Pekora 2 Apr 21, 2022
A reimplementation of the TinyGo drivers package for communicating with multiples of the same (supported) devices on one individual I2C bus.

tinygo-multi-i2c A reimplementation of the TinyGo drivers package for communicating with multiples of the same (supported) devices on one individual I

Quinn Millican 3 Mar 10, 2022
erchive is a go program that compresses and encrypts files and entire directories into .zep files (encrypted zip files).

erchive/zep erchive is a go program that compresses and encrypts files and entire directories into .zep files (encrypted zip files). it compresses usi

Christopher Walters 1 May 16, 2022
Package socket provides a low-level network connection type which integrates with Go's runtime network poller to provide asynchronous I/O and deadline support. MIT Licensed.

socket Package socket provides a low-level network connection type which integrates with Go's runtime network poller to provide asynchronous I/O and d

Matt Layher 41 May 9, 2022
Encode and Decode Message Length Indicators for TCP/IP socket based protocols

SimpleMLI A Message Length Indicator Encoder/Decoder Message Length Indicators (MLI) are commonly used in communications over raw TCP/IP sockets. This

American Express 22 Feb 21, 2022
Native macOS networking for QEMU using vmnet.framework and socket networking.

qemu-vmnet Native macOS networking for QEMU using vmnet.framework and socket networking. Getting started TODO -netdev socket,id=net0,udp=:1234,localad

Alessio Dionisi 20 Jun 14, 2022