.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "Rex::Commands::Pkg 3pm"
.TH Rex::Commands::Pkg 3pm "2020-09-18" "perl v5.28.1" "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"
Rex::Commands::Pkg \- Install/Remove Software packages
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
With this module you can install packages and files.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\& pkg "somepkg",
\&   ensure => "present";
\& pkg "somepkg",
\&   ensure => "latest",
\&   on_change => sub {
\&     say "package was updated.";
\&     service someservice => "restart";
\&   };
\& pkg "somepkg",
\&   ensure => "absent";
.Ve
.SH "EXPORTED FUNCTIONS"
.IX Header "EXPORTED FUNCTIONS"
.ie n .SS "pkg($package, %options)"
.el .SS "pkg($package, \f(CW%options\fP)"
.IX Subsection "pkg($package, %options)"
Since: 0.45
.PP
Use this resource to install or update a package. This resource will generate reports.
.PP
.Vb 3
\& pkg "httpd",
\&   ensure    => "latest",    # ensure that the newest version is installed (auto\-update)
\&   on_change => sub { say "package was installed/updated"; };
\&
\& pkg "httpd",
\&   ensure => "absent";    # remove the package
\&
\& pkg "httpd",
\&   ensure => "present";   # ensure that some version is installed (no auto\-update)
\&
\& pkg "httpd",
\&   ensure => "2.4.6";    # ensure that version 2.4.6 is installed
\&
\& pkg "apache\-server",    # with a custom resource name
\&   package => "httpd",
\&   ensure  => "present";
.Ve
.ie n .SS "install($type, $data, $options)"
.el .SS "install($type, \f(CW$data\fP, \f(CW$options\fP)"
.IX Subsection "install($type, $data, $options)"
The install function can install packages (for CentOS, OpenSuSE and Debian) and files.
.PP
If you need reports, please use the \fBpkg()\fR resource.
.IP "installing a package (This is only supported on CentOS, OpenSuSE and Debian systems.)" 8
.IX Item "installing a package (This is only supported on CentOS, OpenSuSE and Debian systems.)"
.Vb 2
\& task "prepare", "server01", sub {
\&   install package => "perl";
\&
\&   # or if you have to install more packages.
\&   install package => [
\&                  "perl",
\&                  "ntp",
\&                  "dbus",
\&                  "hal",
\&                  "sudo",
\&                  "vim",
\&                ];
\& };
.Ve
.IP "installing a file" 8
.IX Item "installing a file"
This is deprecated since 0.9. Please use File \fIfile\fR instead.
.Sp
.Vb 8
\& task "prepare", "server01", sub {
\&   install file => "/etc/passwd", {
\&                source => "/export/files/etc/passwd",
\&                owner  => "root",
\&                group  => "root",
\&                mode  => 644,
\&              };
\& };
.Ve
.IP "installing a file and do something if the file was changed." 8
.IX Item "installing a file and do something if the file was changed."
.Vb 9
\& task "prepare", "server01", sub {
\&   install file => "/etc/httpd/apache2.conf", {
\&                source   => "/export/files/etc/httpd/apache2.conf",
\&                owner    => "root",
\&                group    => "root",
\&                mode    => 644,
\&                on_change => sub { say "File was modified!"; }
\&              };
\& };
.Ve
.IP "installing a file from a template." 8
.IX Item "installing a file from a template."
.Vb 10
\& task "prepare", "server01", sub {
\&   install file => "/etc/httpd/apache2.tpl", {
\&                source   => "/export/files/etc/httpd/apache2.conf",
\&                owner    => "root",
\&                group    => "root",
\&                mode    => 644,
\&                on_change => sub { say "File was modified!"; },
\&                template  => {
\&                           greeting => "hello",
\&                           name    => "Ben",
\&                         },
\&              };
\& };
.Ve
.PP
This function supports the following hooks:
.IP "before" 4
.IX Item "before"
This gets executed before anything is done. All original parameters are passed to it.
.Sp
The return value of this hook overwrites the original parameters of the function-call.
.IP "before_change" 4
.IX Item "before_change"
This gets executed right before the new package is installed. All original parameters are passed to it.
.Sp
This hook is only available for package installations. If you need file hooks, you have to use the \fBfile()\fR function.
.IP "after_change" 4
.IX Item "after_change"
This gets executed right after the new package was installed. All original parameters, and the fact of change (\f(CW\*(C`{ changed =\*(C'\fR TRUE|FALSE }>) are passed to it.
.Sp
This hook is only available for package installations. If you need file hooks, you have to use the \fBfile()\fR function.
.IP "after" 4
.IX Item "after"
This gets executed right before the \f(CW\*(C`install()\*(C'\fR function returns. All original parameters, and any returned results are passed to it.
.ie n .SS "remove($type, $package, $options)"
.el .SS "remove($type, \f(CW$package\fP, \f(CW$options\fP)"
.IX Subsection "remove($type, $package, $options)"
This function will remove the given package from a system.
.PP
.Vb 3
\& task "cleanup", "server01", sub {
\&   remove package => "vim";
\& };
.Ve
.SS "update_system"
.IX Subsection "update_system"
This function does a complete system update.
.PP
For example \fIapt-get upgrade\fR or \fIyum update\fR.
.PP
.Vb 3
\& task "update\-system", "server1", sub {
\&   update_system;
\& };
.Ve
.PP
If you want to get the packages that where updated, you can use the \fIon_change\fR hook.
.PP
.Vb 11
\& task "update\-system", "server1", sub {
\&   update_system
\&     on_change => sub {
\&       my (@modified_packages) = @_;
\&       for my $pkg (@modified_packages) {
\&         say "Name: $pkg\->{name}";
\&         say "Version: $pkg\->{version}";
\&         say "Action: $pkg\->{action}";   # some of updated, installed or removed
\&       }
\&     };
\& };
.Ve
.PP
Options for \fIupdate_system\fR
.IP "update_metadata" 4
.IX Item "update_metadata"
Set to \fI\s-1TRUE\s0\fR if the package metadata should be updated. Since 1.5 default to \fI\s-1FALSE\s0\fR if possible. Before 1.5 it depends on the package manager.
.IP "update_package" 4
.IX Item "update_package"
Set to \fI\s-1TRUE\s0\fR if you want to update the packages. Default is \fI\s-1TRUE\s0\fR.
.IP "dist_upgrade" 4
.IX Item "dist_upgrade"
Set to \fI\s-1TRUE\s0\fR if you want to run a dist-upgrade if your distribution supports it. Default is \fI\s-1FALSE\s0\fR.
.SS "installed_packages"
.IX Subsection "installed_packages"
This function returns all installed packages and their version.
.PP
.Vb 1
\& task "get\-installed", "server1", sub {
\&
\&    for my $pkg (installed_packages()) {
\&      say "name    : " . $pkg\->{"name"};
\&      say "  version: " . $pkg\->{"version"};
\&    }
\&
\& };
.Ve
.SS "is_installed"
.IX Subsection "is_installed"
This function tests if \f(CW$package\fR is installed. Returns 1 if true. 0 if false.
.PP
.Vb 8
\& task "isinstalled", "server01", sub {
\&   if( is_installed("rex") ) {
\&     say "Rex is installed";
\&   }
\&   else {
\&     say "Rex is not installed";
\&   }
\& };
.Ve
.SS "update_package_db"
.IX Subsection "update_package_db"
This function updates the local package database. For example, on CentOS it will execute \fIyum makecache\fR.
.PP
.Vb 4
\& task "update\-pkg\-db", "server1", "server2", sub {
\&   update_package_db;
\&   install package => "apache2";
\& };
.Ve
.ie n .SS "repository($action, %data)"
.el .SS "repository($action, \f(CW%data\fP)"
.IX Subsection "repository($action, %data)"
Add or remove a repository from the package manager.
.PP
For Debian: If you have no source repository, or if you don't want to add it, just remove the \fIsource\fR parameter.
.PP
.Vb 8
\& task "add\-repo", "server1", "server2", sub {
\&   repository "add" => "repository\-name",
\&      url      => "http://rex.linux\-files.org/debian/squeeze",
\&      key_url  => "http://rex.linux\-files.org/DPKG\-GPG\-KEY\-REXIFY\-REPO"
\&      distro    => "squeeze",
\&      repository => "rex",
\&      source    => 1;
\& };
.Ve
.PP
To specify a key from a file use key_file => '/tmp/mykeyfile'.
.PP
To use a keyserver use key_server and key_id.
.PP
For \s-1ALT\s0 Linux: If repository is unsigned, just remove the \fIsign_key\fR parameter.
.PP
.Vb 7
\& task "add\-repo", "server1", "server2", sub {
\&   repository "add" => "altlinux\-sisyphus",
\&      url      => "ftp://ftp.altlinux.org/pub/distributions/ALTLinux/Sisyphus",
\&      sign_key  => "alt",
\&      arch     => "noarch, x86_64",
\&      repository => "classic";
\& };
.Ve
.PP
For CentOS, Mageia and SuSE only the name and the url are needed.
.PP
.Vb 3
\& task "add\-repo", "server1", "server2", sub {
\&   repository add => "repository\-name",
\&      url => \*(Aqhttp://rex.linux\-files.org/CentOS/$releasever/rex/$basearch/\*(Aq;
\&
\& };
.Ve
.PP
To remove a repository just delete it with its name.
.PP
.Vb 3
\& task "rm\-repo", "server1", sub {
\&   repository remove => "repository\-name";
\& };
.Ve
.PP
You can also use one call to repository to add repositories on multiple platforms:
.PP
.Vb 10
\& task "add\-repo", "server1", "server2", sub {
\&  repository add => myrepo => {
\&    Ubuntu => {
\&      url => "http://foo.bar/repo",
\&      distro => "precise",
\&      repository => "foo",
\&    },
\&    Debian => {
\&      url => "http://foo.bar/repo",
\&      distro => "squeeze",
\&      repository => "foo",
\&    },
\&    CentOS => {
\&      url => "http://foo.bar/repo",
\&    },
\&  };
\& };
.Ve
.ie n .SS "package_provider_for $os => $type;"
.el .SS "package_provider_for \f(CW$os\fP => \f(CW$type\fP;"
.IX Subsection "package_provider_for $os => $type;"
To set another package provider as the default, use this function.
.PP
.Vb 1
\& user "root";
\&
\& group "db" => "db[01..10]";
\& package_provider_for SunOS => "blastwave";
\&
\& task "prepare", group => "db", sub {
\&    install package => "vim";
\& };
.Ve
.PP
This example will install \fIvim\fR on every db server. If the server is a Solaris (SunOS) it will use the \fIblastwave\fR Repositories.