golden hour

/opt/saltstack/salt/lib/python3.10/site-packages/salt/modules

File/Folder	Size	Actions
__init__.py	35 B
__pycache__	-
acme.py	12.74 KB
aix_group.py	4.12 KB
aix_shadow.py	1.93 KB
aixpkg.py	24.15 KB
aliases.py	5.07 KB
alternatives.py	5.71 KB
ansiblegate.py	19.51 KB
apache.py	12.47 KB
apcups.py	2.15 KB
apf.py	3.09 KB
apkpkg.py	16 KB
aptly.py	15.28 KB
aptpkg.py	116.64 KB
archive.py	48.63 KB
arista_pyeapi.py	22.06 KB
artifactory.py	24.78 KB
at.py	10.72 KB
at_solaris.py	8.51 KB
augeas_cfg.py	13.93 KB
aws_sqs.py	6.55 KB
azurearm_compute.py	20.8 KB
azurearm_dns.py	15.8 KB
azurearm_network.py	82.99 KB
azurearm_resource.py	35.75 KB
bamboohr.py	7.36 KB
baredoc.py	11.13 KB
bcache.py	28.97 KB
beacons.py	27.82 KB
bigip.py	69.11 KB
bluez_bluetooth.py	6.76 KB
boto3_elasticache.py	37.34 KB
boto3_elasticsearch.py	53.17 KB
boto3_route53.py	39.82 KB
boto3_sns.py	12.93 KB
boto_apigateway.py	61.86 KB
boto_asg.py	35.69 KB
boto_cfn.py	7.95 KB
boto_cloudfront.py	12.75 KB
boto_cloudtrail.py	14.45 KB
boto_cloudwatch.py	10.99 KB
boto_cloudwatch_event.py	9.48 KB
boto_cognitoidentity.py	14.63 KB
boto_datapipeline.py	6.94 KB
boto_dynamodb.py	14.98 KB
boto_ec2.py	79.27 KB
boto_efs.py	14.05 KB
boto_elasticache.py	23.69 KB
boto_elasticsearch_domain.py	15.85 KB
boto_elb.py	35.53 KB
boto_elbv2.py	10.78 KB
boto_iam.py	75.62 KB
boto_iot.py	26.2 KB
boto_kinesis.py	19.62 KB
boto_kms.py	17.29 KB
boto_lambda.py	35.05 KB
boto_rds.py	34.92 KB
boto_route53.py	32.55 KB
boto_s3.py	4.24 KB
boto_s3_bucket.py	31.8 KB
boto_secgroup.py	25.22 KB
boto_sns.py	7.22 KB
boto_sqs.py	6.43 KB
boto_ssm.py	3.63 KB
boto_vpc.py	113.08 KB
bower.py	5.85 KB
bridge.py	10.81 KB
bsd_shadow.py	6.25 KB
btrfs.py	33.66 KB
cabal.py	3.79 KB
capirca_acl.py	40.04 KB
cassandra_cql.py	54.16 KB
cassandra_mod.py	4.3 KB
celery.py	3.33 KB
ceph.py	15.82 KB
chassis.py	1.52 KB
chef.py	4.66 KB
chocolatey.py	41.55 KB
chronos.py	2.89 KB
chroot.py	11.73 KB
cimc.py	23.02 KB
ciscoconfparse_mod.py	14.79 KB
cisconso.py	3.83 KB
cloud.py	9.39 KB
cmdmod.py	163.73 KB
composer.py	10.31 KB
config.py	16.98 KB
consul.py	69.3 KB
container_resource.py	12.94 KB
cp.py	31.98 KB
cpan.py	5.54 KB
cron.py	28.09 KB
cryptdev.py	10.08 KB
csf.py	16.04 KB
cyg.py	8.32 KB
daemontools.py	5.41 KB
data.py	3.85 KB
datadog_api.py	7.76 KB
ddns.py	7.12 KB
deb_apache.py	7.41 KB
deb_postgres.py	4.18 KB
debconfmod.py	4.06 KB
debian_ip.py	64.91 KB
debian_service.py	6.55 KB
debuild_pkgbuild.py	34.68 KB
defaults.py	6.55 KB
devinfo.py	9.07 KB
devmap.py	627 B
dig.py	8.75 KB
disk.py	30.82 KB
djangomod.py	7.53 KB
dnsmasq.py	5.71 KB
dnsutil.py	11.51 KB
dockercompose.py	32.62 KB
dockermod.py	224.85 KB
dpkg_lowpkg.py	12.94 KB
drac.py	10.97 KB
dracr.py	38.53 KB
drbd.py	7.19 KB
dummyproxy_pkg.py	2.46 KB
dummyproxy_service.py	2.91 KB
ebuildpkg.py	38.74 KB
eix.py	1.58 KB
elasticsearch.py	51.44 KB
environ.py	8.96 KB
eselect.py	4.99 KB
esxcluster.py	1.66 KB
esxdatacenter.py	1.68 KB
esxi.py	2.79 KB
esxvm.py	1.63 KB
etcd_mod.py	8.56 KB
ethtool.py	11.12 KB
event.py	7.67 KB
extfs.py	8.78 KB
file.py	232.18 KB
firewalld.py	20.51 KB
freebsd_sysctl.py	4.99 KB
freebsd_update.py	6.19 KB
freebsdjail.py	7.16 KB
freebsdkmod.py	6.17 KB
freebsdpkg.py	17.04 KB
freebsdports.py	13.13 KB
freebsdservice.py	12.53 KB
freezer.py	10.2 KB
gcp_addon.py	4.07 KB
gem.py	10.6 KB
genesis.py	21.75 KB
gentoo_service.py	9.18 KB
gentoolkitmod.py	8.39 KB
git.py	172.01 KB
github.py	53.19 KB
glanceng.py	4.69 KB
glassfish.py	19.49 KB
glusterfs.py	19.55 KB
gnomedesktop.py	6.85 KB
google_chat.py	1.52 KB
gpg.py	39.09 KB
grafana4.py	30.27 KB
grains.py	21.81 KB
groupadd.py	11.87 KB
grub_legacy.py	3.08 KB
guestfs.py	2.37 KB
hadoop.py	3.76 KB
haproxyconn.py	10.17 KB
hashutil.py	6.77 KB
heat.py	25.25 KB
helm.py	39.27 KB
hg.py	7.16 KB
highstate_doc.py	22.76 KB
hosts.py	10.47 KB
http.py	3.76 KB
icinga2.py	4.46 KB
idem.py	1.75 KB
ifttt.py	2.28 KB
ilo.py	15.98 KB
incron.py	7.68 KB
influxdb08mod.py	15.07 KB
influxdbmod.py	16.13 KB
infoblox.py	17.53 KB
ini_manage.py	14.63 KB
inspectlib	-
inspector.py	8.19 KB
introspect.py	4.02 KB
iosconfig.py	14.78 KB
ipmi.py	25.47 KB
ipset.py	17.97 KB
iptables.py	57.44 KB
iwtools.py	3.99 KB
jboss7.py	20.51 KB
jboss7_cli.py	15.23 KB
jenkinsmod.py	11.9 KB
jinja.py	2.66 KB
jira_mod.py	7.07 KB
junos.py	73.96 KB
k8s.py	24.87 KB
kapacitor.py	5.37 KB
kerberos.py	5.42 KB
kernelpkg_linux_apt.py	6.71 KB
kernelpkg_linux_yum.py	7.26 KB
key.py	1007 B
keyboard.py	2.64 KB
keystone.py	43.14 KB
keystoneng.py	21.82 KB
keystore.py	7.18 KB
kmod.py	7.65 KB
kubeadm.py	34.64 KB
kubernetesmod.py	46.77 KB
launchctl_service.py	9.69 KB
layman.py	4.22 KB
ldap3.py	18.81 KB
ldapmod.py	5.9 KB
libcloud_compute.py	23.48 KB
libcloud_dns.py	9.73 KB
libcloud_loadbalancer.py	13.14 KB
libcloud_storage.py	12.16 KB
linux_acl.py	7.7 KB
linux_ip.py	5.55 KB
linux_lvm.py	17.86 KB
linux_service.py	4.64 KB
linux_shadow.py	12.96 KB
linux_sysctl.py	7.5 KB
localemod.py	11.84 KB
locate.py	2.58 KB
logadm.py	9.44 KB
logmod.py	1.25 KB
logrotate.py	7.72 KB
lvs.py	11.54 KB
lxc.py	147.27 KB
lxd.py	90.07 KB
mac_assistive.py	11.37 KB
mac_brew_pkg.py	19.91 KB
mac_desktop.py	2.77 KB
mac_group.py	6.62 KB
mac_keychain.py	6.39 KB
mac_pkgutil.py	2.84 KB
mac_portspkg.py	11.36 KB
mac_power.py	13.29 KB
mac_service.py	19.64 KB
mac_shadow.py	14.23 KB
mac_softwareupdate.py	14.52 KB
mac_sysctl.py	5.13 KB
mac_system.py	15.07 KB
mac_timezone.py	8.34 KB
mac_user.py	16.41 KB
mac_xattr.py	6.27 KB
macdefaults.py	2.33 KB
macpackage.py	6.66 KB
makeconf.py	17.31 KB
mandrill.py	6.31 KB
marathon.py	5.36 KB
match.py	13 KB
mattermost.py	3.4 KB
mdadm_raid.py	9.86 KB
mdata.py	3.38 KB
memcached.py	6.13 KB
mine.py	18.84 KB
minion.py	7.68 KB
mod_random.py	7.18 KB
modjk.py	12.48 KB
mongodb.py	29.75 KB
monit.py	5.51 KB
moosefs.py	3.87 KB
mount.py	58.44 KB
mssql.py	14.64 KB
msteams.py	2.11 KB
munin.py	2.4 KB
mysql.py	90.66 KB
nacl.py	9.72 KB
nagios.py	6.53 KB
nagios_rpc.py	5.09 KB
namecheap_domains.py	12.84 KB
namecheap_domains_dns.py	5.93 KB
namecheap_domains_ns.py	4.51 KB
namecheap_ssl.py	25.69 KB
namecheap_users.py	2.4 KB
napalm_bgp.py	9.72 KB
napalm_formula.py	11.33 KB
napalm_mod.py	61.37 KB
napalm_netacl.py	28.59 KB
napalm_network.py	93.22 KB
napalm_ntp.py	10.22 KB
napalm_probes.py	13.25 KB
napalm_route.py	5.09 KB
napalm_snmp.py	7.05 KB
napalm_users.py	6.49 KB
napalm_yang_mod.py	20.28 KB
netaddress.py	1.6 KB
netbox.py	32.22 KB
netbsd_sysctl.py	3.92 KB
netbsdservice.py	6.43 KB
netmiko_mod.py	19.61 KB
netscaler.py	27.02 KB
network.py	63.42 KB
neutron.py	44.92 KB
neutronng.py	15.02 KB
nexus.py	22.95 KB
nfs3.py	3.9 KB
nftables.py	33.58 KB
nginx.py	3.83 KB
nilrt_ip.py	36.18 KB
nix.py	8.03 KB
nova.py	19.6 KB
npm.py	10.4 KB
nspawn.py	41.35 KB
nxos.py	24.65 KB
nxos_api.py	14.72 KB
nxos_upgrade.py	14.74 KB
omapi.py	3.6 KB
openbsd_sysctl.py	3.74 KB
openbsdpkg.py	10.97 KB
openbsdrcctl_service.py	6.33 KB
openbsdservice.py	8.31 KB
openscap.py	2.81 KB
openstack_config.py	3.21 KB
openstack_mng.py	2.71 KB
openvswitch.py	17.19 KB
opkg.py	49.67 KB
opsgenie.py	3.29 KB
oracle.py	5.82 KB
osquery.py	24.93 KB
out.py	2.53 KB
pacmanpkg.py	31.92 KB
pagerduty.py	4.7 KB
pagerduty_util.py	13.48 KB
pam.py	2.01 KB
panos.py	61.05 KB
parallels.py	19.85 KB
parted_partition.py	21.53 KB
pcs.py	14.11 KB
pdbedit.py	10.79 KB
pecl.py	3.79 KB
peeringdb.py	8.39 KB
pf.py	9.51 KB
philips_hue.py	1.55 KB
pillar.py	21.37 KB
pip.py	53.42 KB
pkg_resource.py	12.3 KB
pkgin.py	17.29 KB
pkgng.py	61.07 KB
pkgutil.py	9.85 KB
portage_config.py	22.73 KB
postfix.py	16.24 KB
postgres.py	88.24 KB
poudriere.py	7.85 KB
powerpath.py	2.57 KB
proxy.py	11.49 KB
ps.py	20.89 KB
publish.py	10.25 KB
puppet.py	10.9 KB
purefa.py	33.59 KB
purefb.py	13.69 KB
pushbullet.py	1.88 KB
pushover_notify.py	3.48 KB
pw_group.py	4.62 KB
pw_user.py	12.47 KB
pyenv.py	6.93 KB
qemu_img.py	1.53 KB
qemu_nbd.py	3.28 KB
quota.py	6.43 KB
rabbitmq.py	38.4 KB
rallydev.py	6.09 KB
random_org.py	23.76 KB
rbac_solaris.py	16.05 KB
rbenv.py	10.75 KB
rdp.py	6.08 KB
rebootmgr.py	7.68 KB
redismod.py	16.36 KB
reg.py	16.36 KB
rest_pkg.py	2.26 KB
rest_sample_utils.py	558 B
rest_service.py	3.63 KB
restartcheck.py	24.1 KB
restconf.py	3.15 KB
ret.py	1.27 KB
rh_ip.py	38.55 KB
rh_service.py	16.61 KB
riak.py	5.19 KB
rpm_lowpkg.py	27.67 KB
rpmbuild_pkgbuild.py	24.53 KB
rsync.py	8.04 KB
runit.py	17.17 KB
rvm.py	11.1 KB
s3.py	9.93 KB
s6.py	3.62 KB
salt_proxy.py	4.48 KB
salt_version.py	4.58 KB
saltcheck.py	46.66 KB
saltcloudmod.py	954 B
saltutil.py	57.49 KB
schedule.py	50.81 KB
scp_mod.py	6.22 KB
scsi.py	2.66 KB
sdb.py	2.48 KB
seed.py	8.87 KB
selinux.py	24.2 KB
sensehat.py	7.79 KB
sensors.py	1.3 KB
serverdensity_device.py	8.1 KB
servicenow.py	4.36 KB
slack_notify.py	7.83 KB
slackware_service.py	6.84 KB
slsutil.py	19.04 KB
smartos_imgadm.py	12.04 KB
smartos_nictagadm.py	6.46 KB
smartos_virt.py	5.21 KB
smartos_vmadm.py	26.2 KB
smbios.py	10.05 KB
smf_service.py	8.52 KB
smtp.py	5.41 KB
snapper.py	27.14 KB
solaris_fmadm.py	11.2 KB
solaris_group.py	2.8 KB
solaris_shadow.py	7.98 KB
solaris_system.py	3.72 KB
solaris_user.py	11.06 KB
solarisipspkg.py	18.68 KB
solarispkg.py	15.4 KB
solr.py	45.54 KB
solrcloud.py	14.63 KB
splunk.py	8.14 KB
splunk_search.py	8.76 KB
sqlite3.py	2.54 KB
ssh.py	43.89 KB
ssh_pkg.py	1.08 KB
ssh_service.py	3.39 KB
state.py	82.34 KB
status.py	57.79 KB
statuspage.py	14.67 KB
supervisord.py	11.15 KB
suse_apache.py	2.45 KB
suse_ip.py	35.72 KB
svn.py	10.75 KB
swarm.py	13.5 KB
swift.py	5.53 KB
sysbench.py	6.62 KB
sysfs.py	6.61 KB
syslog_ng.py	31.52 KB
sysmod.py	22.59 KB
sysrc.py	3.38 KB
system.py	19.28 KB
system_profiler.py	3.54 KB
systemd_service.py	46.29 KB
telegram.py	3.28 KB
telemetry.py	12.87 KB
temp.py	831 B
test.py	15.4 KB
test_virtual.py	237 B
testinframod.py	9.92 KB
textfsm_mod.py	16.22 KB
timezone.py	19.98 KB
tls.py	58.63 KB
tomcat.py	18.59 KB
trafficserver.py	10.44 KB
transactional_update.py	35.83 KB
travisci.py	2.05 KB
tuned.py	2.34 KB
twilio_notify.py	2.95 KB
udev.py	3.72 KB
upstart_service.py	16.92 KB
uptime.py	3.23 KB
useradd.py	22.63 KB
uwsgi.py	996 B
vagrant.py	20.4 KB
varnish.py	3.08 KB
vault.py	15.61 KB
vbox_guest.py	10.55 KB
vboxmanage.py	14.71 KB
vcenter.py	1.61 KB
victorops.py	6.54 KB
virt.py	287.71 KB
virtualenv_mod.py	15.09 KB
vmctl.py	9.56 KB
vsphere.py	380.41 KB
webutil.py	3.66 KB
win_auditpol.py	4.74 KB
win_autoruns.py	2.29 KB
win_certutil.py	4.55 KB
win_dacl.py	32.27 KB
win_disk.py	1.8 KB
win_dism.py	20.7 KB
win_dns_client.py	4.19 KB
win_dsc.py	27.54 KB
win_event.py	22.32 KB
win_file.py	64.39 KB
win_firewall.py	20.15 KB
win_groupadd.py	11.27 KB
win_iis.py	68.78 KB
win_ip.py	11.43 KB
win_lgpo.py	491.76 KB
win_lgpo_reg.py	17.9 KB
win_license.py	2.72 KB
win_network.py	13.9 KB
win_ntp.py	1.8 KB
win_path.py	11.12 KB
win_pkg.py	86.43 KB
win_pki.py	15.8 KB
win_powercfg.py	9.85 KB
win_psget.py	8.97 KB
win_servermanager.py	14.21 KB
win_service.py	32.96 KB
win_shadow.py	3.03 KB
win_shortcut.py	16.49 KB
win_smtp_server.py	17.67 KB
win_snmp.py	13.38 KB
win_status.py	16.94 KB
win_system.py	40.61 KB
win_task.py	79.17 KB
win_timezone.py	13.3 KB
win_useradd.py	27.39 KB
win_wua.py	38.29 KB
win_wusa.py	5.88 KB
winrepo.py	6.09 KB
wordpress.py	4.71 KB
x509.py	63.1 KB
x509_v2.py	74.15 KB
xapi_virt.py	24.07 KB
xbpspkg.py	15.84 KB
xfs.py	15.35 KB
xml.py	2.14 KB
xmpp.py	5.28 KB
yaml.py	1.94 KB
yumpkg.py	116.5 KB
zabbix.py	97.55 KB
zcbuildout.py	28.16 KB
zenoss.py	5.64 KB
zfs.py	34.44 KB
zk_concurrency.py	11.16 KB
znc.py	2.26 KB
zoneadm.py	15.05 KB
zonecfg.py	21.85 KB
zookeeper.py	14.72 KB
zpool.py	44.02 KB
zypperpkg.py	94.87 KB

Edit: transactional_update.py

"""Transactional update
====================

.. versionadded:: 3004

A transactional system, like `MicroOS`_, can present some challenges
when the user decided to manage it via Salt.

MicroOS provide a read-only rootfs and a tool,
``transactional-update``, that takes care of the management of the
system (updating, upgrading, installation or reboot, among others) in
an atomic way.

Atomicity is the main feature of MicroOS, and to guarantee this
property, this model leverages ``snapper``, ``zypper``, ``btrfs`` and
``overlayfs`` to create snapshots that will be updated independently
of the currently running system, and that are activated after the
reboot.  This implies, for example, that some changes made on the
system are not visible until the next reboot, as those changes are
living in a different snapshot of the file system.

This model presents a lot of problems with the traditional Salt model,
where the inspections (like 'is this package installed?') are executed
in order to determine if a subsequent action is required (like
'install this package').

Lets consider this use case, to see how it works on a traditional
system, and in a transactional system:

1) Check if ``apache`` is installed

2) If it is not installed, install it

3) Check that a ``vhost`` is configured for ``apache``

4) Make sure that ``apache2.service`` is enabled

5) If the configuration changes, restart ``apache2.service``

In the traditional system everything will work as expected.  The
system can see if the package is present or not, install it if it
isn't, and a re-check will shows that is already present.  The same
will happen to the configuration file in ``/etc/apache2``, that will
be available as soon the package gets installed.  Salt can inspect the
current form of this file, and add the missing bits if required.  Salt
can annotate that a change is present, and restart the service.

In a transactional system we will have multiple issues.  The first one
is that Salt can only see the content of the snapshot where the system
booted from.  Later snapshots may contain different content, including
the presence of ``apache``.  If Salt decides to install ``apache``
calling ``zypper``, it will fail, as this will try to write into the
read-only rootfs.  Even if Salt would call ``transactional-update pkg
install``, the package would only be present in the new transaction
(snapshot), and will not be found in the currently running system when
later Salt tries to validate the presence of the package in the
current one.

Any change in ``/etc`` alone will have also problems, as the changes
will be alive in a different overlay, only visible after the reboot.
And, finally, the service can only be enabled and restarted if the
service file is already present in the current ``/etc``.

General strategy
----------------

``transactional-update`` is the reference tool used for the
administration of transactional systems.  Newer versions of this tool
support the execution of random commands in the new transaction, the
continuation of a transaction, the automatic detection of changes in
new transactions and the merge of ``/etc`` overlays.

Continue a transaction
......................

One prerequisite already present is the support for branching from a
different snapshot than the current one in snapper.

With this feature we can represent in ``transactional-update`` the
action of creating a transaction snapshot based on one that is planned
to be the active one after the reboot.  This feature removes a lot of
user complains (like, for example, losing changes that are stored in a
transaction not yet activated), but also provide a more simple model
to work with.

So, for example, if the user have this scenario::

+-----+  *=====*  +--V--+
    --| T.1 |--| T.2 |--| T.3 |
      +-----+  *=====*  +--A--+

where T.2 is the current active one, and T.3 is an snapshot generated
from T.2 with a new package (``apache2``), and is marked to be the
active after the reboot.

Previously, if the user (that is still on T.2) created a new
transaction, maybe for adding a new package (``tomcat``, for example),
the new T.4 will be based on the content of T.2 again, and not T.3, so
the new T.4 will have lost the changes of T.3 (i.e. `apache2` will not
be present in T.4).

With the ``--continue`` parameter, ``transactional-update`` will
create T.4 based on T.3, and nothing will be lost.

Command execution inside a new transaction
..........................................

With ``transactional-update run`` we will create a new transaction
based on the current one (T.2), where we can send interactive commands
that can modify the new transaction, and as commented, with
``transactional-update --continue run``, we will create a new
transaction based on the last created (T.3)

The ``run`` command can execute any application inside the new
transaction namespace.  This module uses this feature to execute the
different Salt execution modules, via ``call()``. Or even the full
``salt-thin`` or ``salt-call`` via ``sls()``, ``apply()``,
``single()`` or ``highstate``.

``transactional-update`` will drop empty snapshots
..................................................

The option ``--drop-if-no-change`` is used to detect whether there is
any change in the file system on the read-only subvolume of the new
transaction will be added.  If a change is present, the new
transaction will remain, if not it will be discarded.

For example::

transactional-update --continue --drop-if-no-change run zypper in apache2"

If we are in the scenario described before, ``apache2`` is already
present in T.3.  In this case a new transaction, T.4, will be created
based on T.3, ``zypper`` will detect that the package is already
present and no change will be produced on T.4.  At the end of the
execution, ``transactional-update`` will validate that T.3 and T.4 are
equivalent and T.4 will be discarded.

If the command is::

transactional-update --continue --drop-if-no-change run zypper in tomcat

the new T.4 will be indeed different from T.3, and will remain after
the transaction is closed.

With this feature, every time that we call any function of this
execution module, we will minimize the amount of transaction, while
maintaining the idempotence so some operations.

Report for pending transaction
..............................

A change in the system will create a new transaction, that needs to be
activated via a reboot.  With ``pending_transaction()`` we can check
if a reboot is needed.  We can execute the reboot using the
``reboot()`` function, that will follow the plan established by the
functions of the ``rebootmgr`` execution module.

``/etc`` overlay merge when no new transaction is created
.........................................................

In a transactional model, ``/etc`` is an overlay file system.  Changes
done during the update are only present in the new transaction, and so
will only be available after the reboot.  Or worse, if the transaction
gets dropped, because there is no change in the ``rootfs``, the
changes in ``/etc`` will be dropped too!.  This is designed like that
in order to make the configuration files for the new package available
only when new package is also available to the user.  So, after the
reboot.

This makes sense for the case when, for example, ``apache2`` is not
present in the current transaction, but we installed it.  The new
snapshot contains the ``apache2`` service, and the configuration files
in ``/etc`` will be accessible only after the reboot.

But this model presents an issue.  If we use ``transactional-update
--continue --drop-if-no-change run <command>``, where ``<command>``
does not make any change in the read-only subvolume, but only in
``/etc`` (which is also read-write in the running system), the new
overlay with the changes in ``/etc`` will be dropped together with the
transaction.

To fix this, ``transactional-update`` will detect that when no change
has been made on the read-only subvolume, but done in the overlay, the
transaction will be dropped and the changes in the overlay will be
merged back into ``/etc`` overlay of the current transaction.

Using the execution module
--------------------------

With this module we can create states that leverage Salt into this
kind of systems::

# Install apache (low-level API)
  salt-call transactional_update.pkg_install apache2

# We can call any execution module
  salt-call transactional_update.call pkg.install apache2

# Or via a state
  salt-call transactional_update.single pkg.installed name=apache2

# We can also execute a zypper directly
  salt-call transactional_update run "zypper in apache2" snapshot="continue"

# We can reuse SLS states
  salt-call transactional_update.apply install_and_configure_apache

# Or apply the full highstate
  salt-call transactional_update.highstate

# Is there any change done in the system?
  salt-call transactional_update pending_transaction

# If so, reboot via rebootmgr
  salt-call transactional_update reboot

# We can enable the service
  salt-call service.enable apache2

# If apache2 is available, this will work too
  salt-call service.restart apache2

Fixing some expectations
------------------------

This module alone is an improvement over the current state, but is
easy to see some limitations and problems:

Is not a fully transparent approach
...................................

The user needs to know if the system is transactional or not, as not
everything can be expressed inside a transaction (for example,
restarting a service inside transaction is not allowed).

Two step for service restart
............................

In the ``apache2` example from the beginning we can observe the
biggest drawback.  If the package ``apache2`` is missing, the new
module will create a new transaction, will execute ``pkg.install``
inside the transaction (creating the salt-thin, moving it inside and
delegating the execution to `transactional-update` CLI as part of the
full state).  Inside the transaction we can do too the required
changes in ``/etc`` for adding the new ``vhost``, and we can enable the
service via systemctl inside the same transaction.

At this point we will not merge the ``/etc`` overlay into the current
one, and we expect from the user call the ``reboot`` function inside
this module, in order to activate the new transaction and start the
``apache2`` service.

In the case that the package is already there, but the configuration
for the ``vhost`` is required, the new transaction will be dropped and
the ``/etc`` overlay will be visible in the live system.  Then from
outside the transaction, via a different call to Salt, we can command
a restart of the ``apache2`` service.

We can see that in both cases we break the user expectation, where a
change on the configuration will trigger automatically the restart of
the associated service.  In a transactional scenario we need two
different steps: or a reboot, or a restart from outside of the
transaction.

.. _MicroOS: https://microos.opensuse.org/

:maintainer:    Alberto Planas <aplanas@suse.com>
:maturity:      new
:depends:       None
:platform:      Linux

"""

import logging

import salt.client.ssh.state
import salt.client.ssh.wrapper.state
import salt.exceptions
import salt.utils.args
from salt.modules.state import _check_queue, _prior_running_states, _wait, running

__func_alias__ = {"apply_": "apply"}

log = logging.getLogger(__name__)

def __virtual__():
    """
    transactional-update command is required.
    """
    global _check_queue, _wait, _prior_running_states, running
    if __utils__["path.which"]("transactional-update"):
        _check_queue = salt.utils.functools.namespaced_function(_check_queue, globals())
        _wait = salt.utils.functools.namespaced_function(_wait, globals())
        _prior_running_states = salt.utils.functools.namespaced_function(
            _prior_running_states, globals()
        )
        running = salt.utils.functools.namespaced_function(running, globals())
        return True
    else:
        return (False, "Module transactional_update requires a transactional system")

def _global_params(self_update, snapshot=None, quiet=False):
    """Utility function to prepare common global parameters."""
    params = ["--non-interactive", "--drop-if-no-change"]
    if self_update is False:
        params.append("--no-selfupdate")
    if snapshot and snapshot != "continue":
        params.extend(["--continue", snapshot])
    elif snapshot:
        params.append("--continue")
    if quiet:
        params.append("--quiet")
    return params

def _pkg_params(pkg, pkgs, args):
    """Utility function to prepare common package parameters."""
    params = []

if not pkg and not pkgs:
        raise salt.exceptions.CommandExecutionError("Provide pkg or pkgs parameters")

if args and isinstance(args, str):
        params.extend(args.split())
    elif args and isinstance(args, list):
        params.extend(args)

if pkg:
        params.append(pkg)

if pkgs and isinstance(pkgs, str):
        params.extend(pkgs.split())
    elif pkgs and isinstance(pkgs, list):
        params.extend(pkgs)

return params

def _cmd(cmd, retcode=False):
    """Utility function to run commands."""
    result = __salt__["cmd.run_all"](cmd)
    if retcode:
        return result["retcode"]

if result["retcode"]:
        raise salt.exceptions.CommandExecutionError(result["stderr"])

return result["stdout"]

def transactional():
    """Check if the system is a transactional system

CLI Example:

.. code-block:: bash

salt microos transactional_update transactional

"""
    return bool(__utils__["path.which"]("transactional-update"))

def in_transaction():
    """Check if Salt is executing while in a transaction

CLI Example:

.. code-block:: bash

salt microos transactional_update in_transaction

"""
    return transactional() and __salt__["chroot.in_chroot"]()

def cleanup(self_update=False):
    """Run both cleanup-snapshots and cleanup-overlays.

Identical to calling both cleanup-snapshots and cleanup-overlays.

self_update
        Check for newer transactional-update versions.

CLI Example:

.. code-block:: bash

salt microos transactional_update cleanup

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update))
    cmd.append("cleanup")
    return _cmd(cmd)

def cleanup_snapshots(self_update=False):
    """Mark unused snapshots for snapper removal.

If the current root filesystem is identical to the active root
    filesystem (means after a reboot, before transactional-update
    creates a new snapshot with updates), all old snapshots without a
    cleanup algorithm get a cleanup algorithm set. This is to make
    sure, that old snapshots will be deleted by snapper. See the
    section about cleanup algorithms in snapper(8).

self_update
        Check for newer transactional-update versions.

CLI Example:

.. code-block:: bash

salt microos transactional_update cleanup_snapshots

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update))
    cmd.append("cleanup-snapshots")
    return _cmd(cmd)

def cleanup_overlays(self_update=False):
    """Remove unused overlay layers.

Removes all unreferenced (and thus unused) /etc overlay
    directories in /var/lib/overlay.

self_update
        Check for newer transactional-update versions.

CLI Example:

.. code-block:: bash

salt microos transactional_update cleanup_overlays

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update))
    cmd.append("cleanup-overlays")
    return _cmd(cmd)

def grub_cfg(self_update=False, snapshot=None):
    """Regenerate grub.cfg

grub2-mkconfig(8) is called to create a new /boot/grub2/grub.cfg
    configuration file for the bootloader.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update grub_cfg snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("grub.cfg")
    return _cmd(cmd)

def bootloader(self_update=False, snapshot=None):
    """Reinstall the bootloader

Same as grub.cfg, but will also rewrite the bootloader itself.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update bootloader snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("bootloader")
    return _cmd(cmd)

def initrd(self_update=False, snapshot=None):
    """Regenerate initrd

A new initrd is created in a snapshot.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update initrd snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("initrd")
    return _cmd(cmd)

def kdump(self_update=False, snapshot=None):
    """Regenerate kdump initrd

A new initrd for kdump is created in a snapshot.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update kdump snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("kdump")
    return _cmd(cmd)

def run(command, self_update=False, snapshot=None):
    """Run a command in a new snapshot

Execute the command inside a new snapshot. By default this snaphot
    will remain, but if --drop-if-no-chage is set, the new snapshot
    will be dropped if there is no change in the file system.

command
        Command with parameters that will be executed (as string or
        array)

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update run "mkdir /tmp/dir" snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot, quiet=True))
    cmd.append("run")
    if isinstance(command, str):
        cmd.extend(command.split())
    elif isinstance(command, list):
        cmd.extend(command)
    else:
        raise salt.exceptions.CommandExecutionError("Command parameter not recognized")
    return _cmd(cmd)

def reboot(self_update=False):
    """Reboot after update

Trigger a reboot after updating the system.

Several different reboot methods are supported, configurable via
    the REBOOT_METHOD configuration option in
    transactional-update.conf(5). By default rebootmgrd(8) will be
    used to reboot the system according to the configured policies if
    the service is running, otherwise systemctl reboot will be called.

self_update
        Check for newer transactional-update versions.

CLI Example:

.. code-block:: bash

salt microos transactional_update reboot

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update))
    cmd.append("reboot")
    return _cmd(cmd)

def dup(self_update=False, snapshot=None):
    """Call 'zypper dup'

If new updates are available, a new snapshot is created and zypper
    dup --no-allow-vendor-change is used to update the
    snapshot. Afterwards, the snapshot is activated and will be used
    as the new root filesystem during next boot.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update dup snapshot="continue"
    """
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("dup")
    return _cmd(cmd)

def up(self_update=False, snapshot=None):
    """Call 'zypper up'

If new updates are available, a new snapshot is created and zypper
    up is used to update the snapshot. Afterwards, the snapshot is
    activated and will be used as the new root filesystem during next
    boot.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update up snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("up")
    return _cmd(cmd)

def patch(self_update=False, snapshot=None):
    """Call 'zypper patch'

If new updates are available, a new snapshot is created and zypper
    patch is used to update the snapshot. Afterwards, the snapshot is
    activated and will be used as the new root filesystem during next
    boot.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update patch snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("patch")
    return _cmd(cmd)

def migration(self_update=False, snapshot=None):
    """Updates systems registered via SCC / SMT

On systems which are registered against the SUSE Customer Center
    (SCC) or SMT, a migration to a new version of the installed
    products can be made with this option.

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update migration snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.append("migration")
    return _cmd(cmd)

def pkg_install(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None):
    """Install individual packages

Installs additional software. See the install description in the
    "Package Management Commands" section of zypper's man page for all
    available arguments.

pkg
        Package name to install

pkgs
        List of packages names to install

args
        String or list of extra parameters for zypper

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update pkg_install pkg=emacs snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.extend(["pkg", "install"])
    cmd.extend(_pkg_params(pkg, pkgs, args))
    return _cmd(cmd)

def pkg_remove(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None):
    """Remove individual packages

Removes installed software. See the remove description in the
    "Package Management Commands" section of zypper's man page for all
    available arguments.

pkg
        Package name to install

pkgs
        List of packages names to install

args
        String or list of extra parameters for zypper

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update pkg_remove pkg=vim snapshot="continue"
    """
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.extend(["pkg", "remove"])
    cmd.extend(_pkg_params(pkg, pkgs, args))
    return _cmd(cmd)

def pkg_update(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None):
    """Updates individual packages

Update selected software. See the update description in the
    "Update Management Commands" section of zypper's man page for all
    available arguments.

pkg
        Package name to install

pkgs
        List of packages names to install

args
        String or list of extra parameters for zypper

self_update
        Check for newer transactional-update versions.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "continue" to indicate the last snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update pkg_update pkg=emacs snapshot="continue"

"""
    cmd = ["transactional-update"]
    cmd.extend(_global_params(self_update=self_update, snapshot=snapshot))
    cmd.extend(["pkg", "update"])
    cmd.extend(_pkg_params(pkg, pkgs, args))
    return _cmd(cmd)

def rollback(snapshot=None):
    """Set the current, given or last working snapshot as default snapshot

Sets the default root file system. On a read-only system the root
    file system is set directly using btrfs. On read-write systems
    snapper(8) rollback is called.

If no snapshot number is given, the current root file system is
    set as the new default root file system. Otherwise number can
    either be a snapshot number (as displayed by snapper list) or the
    word last. last will try to reset to the latest working snapshot.

snapshot
        Use the given snapshot or, if no number is given, the current
        default snapshot as a base for the next snapshot. Use
        "last" to indicate the last working snapshot done.

CLI Example:

.. code-block:: bash

salt microos transactional_update rollback

"""
    if (
        snapshot
        and isinstance(snapshot, str)
        and snapshot != "last"
        and not snapshot.isnumeric()
    ):
        raise salt.exceptions.CommandExecutionError(
            "snapshot should be a number or 'last'"
        )
    cmd = ["transactional-update"]
    cmd.append("rollback")
    if snapshot:
        cmd.append(snapshot)
    return _cmd(cmd)

def pending_transaction():
    """Check if there is a pending transaction

CLI Example:

.. code-block:: bash

salt microos transactional_update pending_transaction

"""
    # If we are running inside a transaction, we do not have a good
    # way yet to detect a pending transaction
    if in_transaction():
        raise salt.exceptions.CommandExecutionError(
            "pending_transaction cannot be executed inside a transaction"
        )

cmd = ["snapper", "--no-dbus", "list", "--columns", "number"]
    snapshots = _cmd(cmd)

return any(snapshot.endswith("+") for snapshot in snapshots)

def call(function, *args, **kwargs):
    """Executes a Salt function inside a transaction.

The chroot does not need to have Salt installed, but Python is
    required.

function
        Salt execution module function

activate_transaction
        If at the end of the transaction there is a pending activation
        (i.e there is a new snaphot in the system), a new reboot will
        be scheduled (default False)

CLI Example:

.. code-block:: bash

salt microos transactional_update.call test.ping
        salt microos transactional_update.call ssh.set_auth_key user key=mykey
        salt microos transactional_update.call pkg.install emacs activate_transaction=True

"""

if not function:
        raise salt.exceptions.CommandExecutionError("Missing function parameter")

activate_transaction = kwargs.pop("activate_transaction", False)

try:
        safe_kwargs = salt.utils.args.clean_kwargs(**kwargs)
        salt_argv = (
            [
                "salt-call",
                "--out",
                "json",
                "-l",
                "quiet",
                "--no-return-event",
                "--",
                function,
            ]
            + list(args)
            + ["{}={}".format(k, v) for (k, v) in safe_kwargs.items()]
        )

try:
            ret_stdout = run([str(x) for x in salt_argv], snapshot="continue")
        except salt.exceptions.CommandExecutionError as e:
            # This happens when there was an problem with salt-call execution
            ret_stdout = e.message

# Process "real" result in stdout
        try:
            data = __utils__["json.find_json"](ret_stdout)
            local = data.get("local", data)
            if isinstance(local, dict):
                if "retcode" in local:
                    __context__["retcode"] = local["retcode"]
                return local.get("return", local)
            else:
                return local
        except ValueError:
            return {"result": False, "retcode": 1, "comment": ret_stdout}
    finally:
        # Check if reboot is needed
        if activate_transaction and pending_transaction():
            reboot()

def apply_(mods=None, **kwargs):
    """Apply an state inside a transaction.

This function will call `transactional_update.highstate` or
    `transactional_update.sls` based on the arguments passed to this
    function. It exists as a more intuitive way of applying states.

For a formal description of the possible parameters accepted in
    this function, check `state.apply_` documentation.

activate_transaction
        If at the end of the transaction there is a pending activation
        (i.e there is a new snaphot in the system), a new reboot will
        be scheduled (default False)

CLI Example:

.. code-block:: bash

salt microos transactional_update.apply
        salt microos transactional_update.apply stuff
        salt microos transactional_update.apply stuff pillar='{"foo": "bar"}'
        salt microos transactional_update.apply stuff activate_transaction=True

"""
    if mods:
        return sls(mods, **kwargs)
    return highstate(**kwargs)

def sls(mods, activate_transaction=False, queue=False, **kwargs):
    """Execute the states in one or more SLS files inside a transaction.

saltenv
        Specify a salt fileserver environment to be used when applying
        states

mods
        List of states to execute

test
        Run states in test-only (dry-run) mode

exclude
        Exclude specific states from execution. Accepts a list of sls
        names, a comma-separated string of sls names, or a list of
        dictionaries containing ``sls`` or ``id`` keys. Glob-patterns
        may be used to match multiple states.

activate_transaction
        If at the end of the transaction there is a pending activation
        (i.e there is a new snaphot in the system), a new reboot will
        be scheduled (default False)

queue
        Instead of failing immediately when another state run is in progress,
        queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this
        option sparingly. (Default: False)

For a formal description of the possible parameters accepted in
    this function, check `state.sls` documentation.

CLI Example:

.. code-block:: bash

salt microos transactional_update.sls stuff pillar='{"foo": "bar"}'
        salt microos transactional_update.sls stuff activate_transaction=True

"""
    conflict = _check_queue(queue, kwargs)
    if conflict is not None:
        return conflict

concurrent = kwargs.pop("concurrent", True)

return call(
        "state.sls",
        mods,
        activate_transaction=activate_transaction,
        concurrent=concurrent,
        **kwargs
    )

def highstate(activate_transaction=False, queue=False, **kwargs):
    """Retrieve the state data from the salt master for this minion and
    execute it inside a transaction.

For a formal description of the possible parameters accepted in
    this function, check `state.highstate` documentation.

activate_transaction
        If at the end of the transaction there is a pending activation
        (i.e there is a new snaphot in the system), a new reboot will
        be scheduled (default False)

queue
        Instead of failing immediately when another state run is in progress,
        queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this
        option sparingly. (Default: False)

CLI Example:

.. code-block:: bash

salt microos transactional_update.highstate
        salt microos transactional_update.highstate pillar='{"foo": "bar"}'
        salt microos transactional_update.highstate activate_transaction=True

"""
    conflict = _check_queue(queue, kwargs)
    if conflict is not None:
        return conflict

return call(
        "state.highstate",
        activate_transaction=activate_transaction,
        concurrent=True,
        **kwargs
    )

def single(fun, name, activate_transaction=False, queue=False, **kwargs):
    """Execute a single state function with the named kwargs, returns
    False if insufficient data is sent to the command

By default, the values of the kwargs will be parsed as YAML. So,
    you can specify lists values, or lists of single entry key-value
    maps, as you would in a YAML salt file. Alternatively, JSON format
    of keyword values is also supported.

activate_transaction
        If at the end of the transaction there is a pending activation
        (i.e there is a new snaphot in the system), a new reboot will
        be scheduled (default False)

queue
        Instead of failing immediately when another state run is in progress,
        queue the new state run to begin running once the other has finished.

This option starts a new thread for each queued state run, so use this
        option sparingly. (Default: False)

CLI Example:

.. code-block:: bash

salt microos transactional_update.single pkg.installed name=emacs
        salt microos transactional_update.single pkg.installed name=emacs activate_transaction=True

"""
    conflict = _check_queue(queue, kwargs)
    if conflict is not None:
        return conflict

return call(
        "state.single",
        fun=fun,
        name=name,
        activate_transaction=activate_transaction,
        concurrent=True,
        **kwargs
    )