This page describes most common real-life usecases.
The client tools is called sgl and has to be executed as a superuser (root). The repository is protected and anyone else should be able to access it.
To enable Sandglass versioning, a local repository has to be initialized first.
[root@f14 ~]# sgl init
Initialized Sandglass storage.
Imported configuration within '/etc'.
This command may take a few seconds, depending on an amount of installed packages. Information about configuration files are collected from RPM package database. A cache is created during this process to accelerate a future operations. If the repository is already initialized, the initialization can be forced by --force command line option.
[root@f14 ~]# sgl init
ERROR: Repository is already initialized.
[root@f14 ~]# sgl init --force
Initialized Sandglass storage.
Imported configuration within '/etc'.
Subcommand log can be used to verify this step.
[root@f14 ~]# sgl log
08afc79 2011-05-16 07:33:20 +0200 - initial import of /etc
After some changes are done in the versioned configuration, command sgl status will inform about it.
[root@f14 ~]# useradd john
[root@f14 ~]# sgl status
Changes in package setup:
/etc/group modification
/etc/passwd modification
first change: 3 seconds ago
last change: 3 seconds ago
autocommit: in 19 minutes
The content of the changes can be shown as well.
[root@f14 ~]# sgl diff
diff --sgl a/etc/group b/etc/group
index 4aab6d3..c30b676 100644
mode 0644 0644
owner root:root root:root
context system_u:object_r:etc_t:s0 system_u:object_r:etc_t:s0
--- a/etc/group
+++ b/etc/group
@@ -32,3 +32,4 @@ mailnull:x:47:
smmsp:x:51:
sshd:x:74:
sglserver:x:500:
+john:x:501:
diff --sgl a/etc/passwd b/etc/passwd
index 6913acc..099bcfe 100644
mode 0644 0644
owner root:root root:root
context system_u:object_r:etc_t:s0 system_u:object_r:etc_t:s0
--- a/etc/passwd
+++ b/etc/passwd
@@ -18,3 +18,4 @@ mailnull:x:47:47:x:/var/spool/mqueue:/sbin/nologin
smmsp:x:51:51::/var/spool/mqueue:/sbin/nologin
sshd:x:74:74:Privilege-separated SSH:/var/empty/sshd:/sbin/nologin
sglserver:x:500:500:sglserver:/var/lib/sandglass/server:/bin/bash
+john:x:501:501::/home/john:/bin/bash
The recovery of previous state of one file is possible using.
[root@f14 ~]# sgl recover --files /etc/passwd
Sucessfully recovered.
[root@f14 ~]# sgl status
Changes in package setup:
/etc/group modification
first change: 9 minutes ago
last change: 5 seconds ago
autocommit: in 19 minutes
All changes can be reverted using sgl recover --all command.
Performed changes can be also committed:
[root@f14 ~]# sgl commit -m "add user johndoe"
[root@f14 ~]# sgl log
b589205 2011-05-16 07:50:57 +0200 - add user johndoe
08afc79 2011-05-16 07:33:20 +0200 - initial import of /etc
To add files to be watched by Sandglass, use sgl add command. By default, only configuration files can be added:
[root@f14 /]# sgl add /opt/foo
ERROR: There are no configuration files in '/opt/foo'.
This can be bypassed by adding --everything option or by specifying the files (not the whole directory).
[root@f14 ~]# sgl add /opt/foo/bar.conf
[root@f14 ~]# sgl log
9465d41 2011-05-16 08:01:55 +0200 - add /opt/foo/bar.conf
b589205 2011-05-16 07:50:57 +0200 - add user johndoe
08afc79 2011-05-16 07:33:20 +0200 - initial import of /etc
To remove files from versioning system, use sgl remove command. Please note, that the file is removed only from versioning. The file is not touched at all.
[root@f14 ~]# sgl remove /etc/adjtime
[root@f14 ~]# sgl log
9427daa 2011-05-16 08:03:26 +0200 - remove /etc/adjtime
9465d41 2011-05-16 08:01:55 +0200 - add /opt/foo/bar.conf
b589205 2011-05-16 07:50:57 +0200 - add user johndoe
08afc79 2011-05-16 07:33:20 +0200 - initial import of /etc
The primary tool used for listing changes in repository is sgl log (which was already shown a few times). The first column in the output list is a revision identifier, then there is a time information and short commit message. To show content of any revision, use sgl show followed by revision name. If revision name is ommited, the last revision is shown.
[root@f14 ~]# sgl show 9465d41
commit 9465d41123cca7cebbc21ef6ce87295e4a50c061
Author: root (f14) <root@f14>
Date: Mon May 16 08:01:55 2011 +0200
add /opt/foo/bar.conf
diff --sgl a/opt/foo/bar.conf b/opt/foo/bar.conf
new file mode 100644
index 0000000..afa2033
mode - 0644
owner - root:root
context - -
--- a/opt/foo/bar.conf
+++ b/opt/foo/bar.conf
@@ -0,0 +1,5 @@
+[fruits]
+apple = True
+banana = True
+carrot = True
+plum = True
Content of any file from history at a given time (revision) can be print on the standard output using sgl dump.
[root@f14 /]# sgl dump b589205 /etc/default/useradd
# useradd defaults file
GROUP=100
HOME=/home
INACTIVE=-1
EXPIRE=
SHELL=/bin/bash
SKEL=/etc/skel
CREATE_MAIL_SPOOL=yes
You can also specify a time information. (Specifying the time information will also work with other where revision identifier is accepted.)
[root@f14 /]# sgl dump "@{1 hour ago}" /opt/foo/bar.conf
ERROR: "Blob or Tree named 'opt' not found"
[root@f14 /]# sgl dump "@{1 minute ago}" /opt/foo/bar.conf
[fruits]
apple = True
banana = True
carrot = True
plum = True
How to use sgl diff to show a difference between a revision and working tree was already shown. This command can be also used to display difference between two revisions.
[root@f14 /]# sgl diff "@{1 hour ago}" 9427daa --files /etc/adjtime
diff --sgl a/etc/adjtime b/etc/adjtime
deleted file mode 100644
index 305de74..0000000
mode 0644 -
owner root:root -
context system_u:object_r:adjtime_t:s0 -
--- a/etc/adjtime
+++ b/etc/adjtime
@@ -1,3 +0,0 @@
--0.005302 1305591227 0.000000
-1305591227
-UTC
Command sgl recover was already shown.
System for automatic commiting will occasionally commit your changes automatically. This happens approximately in 20 minutes after the file (or a group of files which belongs to the same package) was modified for the last time.:
[root@f14 ~]# sgl status
Changes in package openldap:
/etc/openldap/ldap.conf modification
first change: 33 minutes ago
last change: 19 minutes ago
autocommit: very soon
To temporary disable creation of automatic commits for particular package, use sgl stall command.
[root@f14 /]# sgl stall openldap
Autocommitting disabled. Use 'sgl auto' to re-enable.
[root@f14 /]# sgl status
Changes in package openldap:
/etc/openldap/ldap.conf modification
first change: 33 minutes ago
last change: 19 minutes ago
autocommit: stalled
You can work on any other changes. After you are done, you can re-enable the autocommiting system using sgl auto command.
[root@f14 /]# sgl auto openldap
Autocommitting re-enabled.
[root@f14 /]# sgl status
Changes in package openldap:
/etc/openldap/ldap.conf modification
first change: 35 minutes ago
last change: 1 minute ago
autocommit: in 18 minutes
Both commands (sgl stall and sgl auto) can be used with option --all, which have the same effect for all packages.
Autocommit system can be configured in Sandglass configuration file (/etc/sandglass.con).
For setting up the configuration on the server please refer to Server Tutorial.
To display currently set remote server, use command sgl remote without any options.
[root@f14 /]# sgl remote
No remote server is set.
The server can be set with the same command. Command sgl sync will force the immediate synchroniation.
[root@f14 /]# sgl remote rawhide
Remote server updated. Use 'sgl sync' to perform the synchronization.
Synchronization with remote server 'rawhide' enabled.
[root@f14 /]# sgl sync
Synchronization is done.
Please note, that this version is not very stable at the moment. Some problems might occur during usage. If some sgl command returns error message from unknown reason, maybe something went wrong. You can use --debug option to see the stack trace. This might help with resolving the problem.
[root@f14 /]# sgl dump /etc/nothing
ERROR: "Blob or Tree named 'nothing' not found"
[root@f14 /]# sgl --debug dump /etc/nothing
ERROR: "Blob or Tree named 'nothing' not found"
Traceback (most recent call last):
File "/usr/sbin/sgl", line 246, in <module>
args.command(args, sgl)
File "/usr/sbin/sgl", line 209, in dump
print sgl.dump(args.file, args.commit), # no-end-line
File "/usr/lib/python2.7/site-packages/sandglass/interface.py", line 24, in delegator
return delegee_method(*args, **kwargs)
File "/usr/lib/python2.7/site-packages/sandglass/repository.py", line 17, in inner
return method(self, *args, **kwargs)
File "/usr/lib/python2.7/site-packages/sandglass/clientrepository.py", line 134, in dump
return commit.tree[filename].data
File "/usr/lib/python2.7/site-packages/git/objects/tree.py", line 231, in __getitem__
return self.__div__(item)
File "/usr/lib/python2.7/site-packages/git/objects/tree.py", line 165, in __div__
item = tree[token]
File "/usr/lib/python2.7/site-packages/git/objects/tree.py", line 231, in __getitem__
return self.__div__(item)
File "/usr/lib/python2.7/site-packages/git/objects/tree.py", line 183, in __div__
raise KeyError( msg % file )
KeyError: "Blob or Tree named 'nothing' not found"