.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "MUNIN-GET 1p"
.TH MUNIN-GET 1p 2024-05-20 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH Name
.IX Header "Name"
munin-get \- a simple tool for managing plugins from remote repositories
.SH Features
.IX Header "Features"
The small management tool "munin-get" supports the following actions:
.IP "clone one or more git repositories containing munin plugins" 4
.IX Item "clone one or more git repositories containing munin plugins"
.PD 0
.IP "multiple remote repositories can be used" 4
.IX Item "multiple remote repositories can be used"
.IP "list all found plugins (including change timestamp and description)" 4
.IX Item "list all found plugins (including change timestamp and description)"
.IP """install"" a plugin (by default to: /var/lib/munin/munin\-get\-plugins)" 4
.IX Item """install"" a plugin (by default to: /var/lib/munin/munin-get-plugins)"
.IP """enable"" a plugin (create a symlink to /etc/munin/plugins/)" 4
.IX Item """enable"" a plugin (create a symlink to /etc/munin/plugins/)"
.IP "upgrade plugins (and review changes before)" 4
.IX Item "upgrade plugins (and review changes before)"
.PD
.PP
The primary purpose of this tool is the simplification of the process of using plugins from munin's
contrib repository.
.SH Usage
.IX Header "Usage"
All actions except "install", "enable" and "disable" can be run as a regular user.  Please note
that the non-privileged commands use directories relative to \f(CW$HOME\fR by default (can be overridden).
Thus sudo or a similar tool should be used for gaining privileges.  Of course, everything can also
be done as root.
.PP
The separate "install" step works around potential problems with systemd hardening flags or other
security policies, which may prevent files in /root/ or below /home/ from being accessed by
the "munin-node" service process.
.SH Examples
.IX Header "Examples"
.SS "Discover, inspect, install, enable and test a plugin"
.IX Subsection "Discover, inspect, install, enable and test a plugin"
.Vb 8
\&    munin\-get update
\&    munin\-get list
\&    munin\-get search throughput
\&    munin\-get doc contrib/traffic
\&    munin\-get install contrib/traffic
\&    munin\-get enable contrib/traffic
\&    munin\-run traffic
\&    service munin\-node restart   # for systemd: systemctl restart munin\-node
.Ve
.SS "Review and apply changes from the upstream repository"
.IX Subsection "Review and apply changes from the upstream repository"
.Vb 4
\&    munin\-get update
\&    munin\-get list\-upgradeable
\&    munin\-get diff\-upgradeable
\&    munin\-get upgrade
.Ve
.SS "Add custom 3rd party git repositories"
.IX Subsection "Add custom 3rd party git repositories"
.Vb 3
\&    munin\-get add\-repository foo http://example.org/repos/munin\-plugins.git
\&    munin\-get add\-repository bar http://example.org/repos/munin\-stuff.git branch\-tested plugins/
\&    munin\-get update
.Ve
.SH Internals
.IX Header "Internals"
Repositories are cloned below ~/.cache/munin/munin\-get/repositories (see REPOSITORY_CACHE_BASE_DIR).
.PP
Manual changes in the cloned repositories should be avoided.
.PP
The separate "install" and "enable" procedure is necessary due to possible process namespace /
hardening features enabled for "munin-node". Thus the target of the symlink is located in a path
that can be expected to be usable even for a restricted "munin-node" process.
.PP
Additionally the separate "install" location allows the manual review of upstream changes before
applying these locally.
.SH Author
.IX Header "Author"
Lars Kruse <devel@sumpfralle.de>
.SH License
.IX Header "License"
.Vb 1
\&  GPLv3+
.Ve