4. Customization¶
When talking about customization, we should distinguish between:
4.1. Server customization¶
GIS.lab Server (master node) can be customized by running standard Linux/Ubuntu commands. See GISMentors training group customization for example of customization performed by specific Ansible Playbooks.
But it is recommended to use some isolated environment like LXC or Docker containers when deploying custom service. See Gisquick integration section for example of such customization.
4.2. User accounts customization¶
Process of creation and removal of GIS.lab user accounts can be customized by special scripts.
Important
Scripts must have executable permissions assigned and
can’t contain file extension, see man run-parts
.
Directory /opt/gislab/custom/accounts
in
Fig. 4.1 (located on GIS.lab master node) contains
following directories with customization scripts.
before-add
- executed before account is createdafter-add
- executed after account is deletedbefore-delete
- executed before account is deletedafter-delete
- executed after account is deletedfiles
- content of this directory is copied to user’s home directory beforeafter-add
hooks are executed
In above customization scripts it is possible to use various
variables. When creating or deleting GIS.lab user account using
gislab-adduser
and gislab-deluser
administration commands,
following variables can be used.
GISLAB_USER
- user name
GISLAB_USER_GIVEN_NAME
- first name
GISLAB_USER_SURNAME
- last name
GISLAB_USER_EMAIL
- email
GISLAB_USER_DESCRIPTION
- description
GISLAB_USER_SUPERUSER
- superuser status
GISLAB_USER_GROUPS
- groups membership
For content stored in files
directory, it is possible to use
template variables in following format.
gislab-adduser
{+ GISLAB_USER +}
- user name{+ GISLAB_USER_GIVEN_NAME +}
- first name{+ GISLAB_USER_SURNAME +}
- last name{+ GISLAB_USER_EMAIL +}
- email{+ GISLAB_USER_DESCRIPTION +}
- description{+ GISLAB_USER_SUPERUSER +}
- superuser status{+ GISLAB_USER_GROUPS+}
- groups membership
Example customization script db
in after-add
directory for
automatic database schema creation in schemaname after new GIS.lab
user is added is shown below.
#!/bin/sh
create_schema() {
if [ ! -z `sudo -u postgres psql -lqt | cut -d \| -f 1 | grep -w $1` ]; then
echo "CREATE SCHEMA $GISLAB_USER;
GRANT USAGE on SCHEMA $GISLAB_USER to $GISLAB_USER;
GRANT SELECT ON ALL TABLES IN SCHEMA $GISLAB_USER TO $GISLAB_USER;
GRANT all ON SCHEMA $GISLAB_USER to $GISLAB_USER" | \
sudo -u postgres psql $1
fi
}
create_schema schemaname
exit 0
4.3. Client customization¶
GIS.lab desktop client can be customized by running standard
Linux/Ubuntu commands as well as GIS.lab server. Difference is that they must be executed in
isolated environment called chroot. Administrator commands
gislab-client-shell
and gislab-client-image
are used to
perform this action.
Fundamental is an image file. It is a binary file with the
.img
filename extension and represents a snapshot GIS.lab
client operating system. More specifically, it is compressed client’s
root
. GIS.lab clients boots from this image. The first of
above mentioned commands enables to enter chroot environment. The
second command creates a new updated image file.
Danger
Client’s root
and resulting image
are always restored
to original state after every GIS.lab upgrade, so customization must be
applied again.
Important danger note written above is precisely why backup should
always be used. In general, it is very good idea to backup client’s
root
and also image
in case if something will go wrong in
process of customization or rollback is required. Approximate total
backup size is about 3 GB.
Backup of client’s root
directory can be created by following statement
using tape archive command.
Command for client’s image
backup is introduced below.
$ sudo tar cjf /mnt/backup/<root>.tar.bz2 /opt/gislab/system/clients/desktop/root
$ sudo cp -a /opt/gislab/system/clients/desktop/image /mnt/backup/<image>
See Fig. 4.2 for clearer understanding.
Note
Backup of client’s image
file is not necessary because
it can always be created by gislab-client-image
command from particular
GIS.lab client’s root
. Why also this backup is useful will be introduced later.
When the recommended backups are created, it is time to start with customization.
See also
See practical example of custom installation of latest GDAL version on GIS.lab client from source code.
Backups of client’s root
and image
is possible to recover
if needed. First, current client’s root
and image
should be
removed and afterwards, selected backup can be recovered, see commands
below.
$ sudo rm -r /opt/gislab/system/clients/desktop/root
$ sudo rm -r /opt/gislab/system/clients/desktop/image
$ sudo tar xjf /mnt/backup/<root>.tar.bz2 -C /
$ sudo cp -a /mnt/backup/<image>/ /opt/gislab/system/clients/desktop/image
Using symbolic links
Violet diagram with blue line color called image
in Fig. 4.2
containing gislab.img
binary file and
gislab-desktop.buildstamp
in
/opt/gislab/system/clients/desktop
directory can be a
directory or a symbolic link. By default it is a directory.
But it is very smart and handy to have more versions of image and just
switching between them by symlink with nickname image
and refer to
particular directory with gislab.img
and
gislab-desktop.buildstamp
files .
Let’s say there are two different images for two different courses - beginner and advanced . They cause different customization of users.
When one wants to select desired image, following steps from
/opt/gislab/system/clients/desktop
directory should be used.
# get list of all saved versions of image
$ (cd /mnt/backup/; ls -la)
root-advanced
root-beginner
root-advanced.tar.bz2
root-beginner.tar.bz2
...
# remove current image and root
$ sudo rm -r image
$ sudo rm -r root
# switch to image for advanced course
$ sudo ln -s /mnt/backup/root-advanced image
# extract corresponding root from backup
$ sudo tar xjf /mnt/backup/root-advanced.tar.bz2 -C /
Then continue with creation of new user prepared for advanced course. See principle in Fig. 4.3.
Note
When new image is set up on master, the clients are notified about new image and rebooted automatically after logout.
It is recommended to use Ansible to execute customization scripts directly from local controlling machine. See Executing customization scripts from Ansible example.
4.4. Boot loader¶
To customize GIS.lab Desktop client boot loader (see
HTTP boot), create copy of boot loader source file
http-boot/gislab-bootloader.ipxe
and modify it as
required. For more information about iPXE syntax see documentation. Than follow build process below.
Firstly, download iPXE source code.
$ git clone git://git.ipxe.org/ipxe.git && cd ipxe
Optionally checkout to version used by GIS.lab by typing
$ git checkout d644ad41f5a17315ab72f6ebeeecf895f7d41679
Finally build customized ISO image bin/ipxe.iso
$ cd src
$ make EMBED=CUSTOM-BOOT-LOADER-SOURCE-FILE.ipxe