Using an existing LDAP data source for attributes and

authentication REFERENCES FOR SELF-STUDY:

1. https://gluu.org/docs/oxtrust/configuration//#manage-authentication

2. https://gluu.org/docs/oxtrust/configuration//#default-authentication-method

3. https://gluu.org/docs/oxtrust/configuration//#cache-refresh

4. http://www.gluu.org/docs/cache-refresh/

5. https://gluu.org/docs/gluu-defaults/schema/

6. https://wiki.gluu.info/doku.php?id=appliance:ssoworkflow

7. http://idmdude.com/2014/01/01/opendj-indexes-explained/

8. http://blogs.technet.com/b/ad/archive/2008/04/01/how-to-create-a-mosiac-of-user-

thumbnails-in-aduc-dsa-msc.aspx

9. https://technet.microsoft.com/en-us/library/ee198834.aspx

10. https://msdn.microsoft.com/en-us/library/ms675095%28v=vs.85%29.aspx

11. http://social.technet.microsoft.com/wiki/contents/articles/22653.active-directory-

ambiguous-name-resolution.aspx

!CAUTION! While following this guide you can easily become locked out from oxTrust,

the Gluu Server administration interface, by making a mistake. You may also want to

revert back to your original state. Make a backup of your current configuration

before proceeding! One easy way to do this is to stop your ldap server (for example, in

Community Edition, # service opendj stop), and then tar and gzip /opt/opendj. Before you start, it would also be a good time to take a virtual machine snapshot, or

run a server backup, if you have that capability.

INTRODUCTION

The Gluu Server offers three strategies for user management:

1. Manual administration using a Web interface (useful only for small

organizations)

2. Connection to an existing Identity Management (IDM) system using the

Gluu Server SCIM or LDAP interfaces

3. LDAP Synchronization

This last option is particularly handy for many organizations, large and small,

because in many cases, business processes exist to keep an LDAP server updated with

the latest user information. This is especially true for organizations that already use

Microsoft Active Directory, a Windows domain controller with LDAP interfaces. The

Gluu Server enables organizations to customize which people and which attributes to

synchronize.

ASSUMPTIONS

This guide assumes you already have an LDAP server, and are familiar with its

operation. You should at least be familiar with OpenDJ, which is built into the Gluu

Server to store the cached user information from the backend datasource. If you need

more information on OpenDJ, read the OpenDJ Administrator Guide to fill in any gaps

in your knowledge. It is also assumed your are familiar with LDAP search conventions

and know how to specify the base, scope and filters. The command line tools

ldapsearch and ldapmodify are really useful for debugging, and you will benefit a lot

by learning how to use them. For those who prefer GUI-enabled tools, perhaps take a

look at jxplorer, a graphical ldap browser.

NOW IT’S TIME TO GET STARTED!

I. Configure Cache Refresh in oxTrust

oxTrust Cache Refresh consolidates identity information from one or more

LDAP backends, and caches the data as a single entry under

“ou=people,o=<org-inum>,o=gluu” in the Gluu OpenDJ server. The Cache Refresh

process also uses another OpenDJ database, “o=site”, to actually map users in the

1

backend system map to users in the internal database/hash entries in the cache files. If

you are not using the Cache Refresh feature, you don’t need the “o=site” database.

The advantage of Cache Refresh is that SSO services like SAML and OpenID

Connect already have the attributes (or “user claims”) needed to return to applications.

It keeps the IDP configuration simple--attributes are always retrieved from the Gluu

OpenDJ server.

Cache Refresh also leverages an interception script to enable the transformation

or creation of LDAP attributes. For example, you may need to change a value, call an

API, or remove some data. This script is run whenever a change is detected and the

cache values are updated. This is another advantage of Cache Refresh--avoiding

dynamic attribute generation in the Shibboleth IDP.

Follow these steps to configure CR (Active Directory will serve as a backend in

this example):

1. Log in to oxTrust as an user with administrative privileges

2. Move to the “Configuration -> Cache Refresh” page

3. In case you are still using Gluu CE package of version prior to 2.4.0, unfold all

configuration sections there so you could be sure values have been supplied for

all mandatory fields on the page. Back then, in cases when one of them

contained such field for which no value was provided, it wouldn’t been

unfolded automatically upon clicking “Update” button (even worse, they would

all become folded after clicking it), so you wouldn’t been able to see it marked

red immediately, what made it look like your settings were accepted, while they

were not.

4. Fill in fields of the “Customer Backend key/attributes” tab as follows (omit

double quotes for values):

a. “Key attribute”: this should be an indexed and unique attribute, which is

guaranteed to have value assigned to it for any existing object, as it will

be used in request in conjunction with “Object class” attribute;

“sAMAccountName” is a number one choice for AD (though exceptions,

like custom schema modifications, involving additions of new unique

indexed attributes, exist), and for many *nix implementations of LDAP

storage that will be “uid” attribute

b. “Object class”: use “user” for AD, but make sure there is no computer

objects under branches provided in “Base DN” list, as they are “users” too,

from its “point of view”; objectclass to use for implementations other

2

than AD may vary greatly

c. “Source attribute”: provide “cn”, “sn”, “mail”, “givenName” and

“displayName” there; this is the list of additional attributes that will be

requested (the attribute designated as key will be added to this list

implicitly), and also the source attributes you’ll be mapping to your

instance’s internally defined attributes latter on (on step 7-e), so Gluu

would be able to release them while serving requests from external

SAML Service Providers or OpenID Connect Relying parties. Caution: please see explanation about requirements imposed by the Gluu’s LDAP

schema on the set of attributes you must provide in the mapping section

of this HOW-TO

d. “Custom LDAP filter”: leave it empty for now; it can be used to expand a

base request composed from values in “Key attribute” and “Object class”

fields; string specified here will be added to it using “&” (“AND”)

operator, and may contain all typical syntactic constructions can be seen

in LDAP filters; for example, this string will limit query results to users

with email addresses starting with “a“ or “b”: |(mail=a*)(mail=b*) ; in case of

an AD’s Organizational Unit in which a mix of user and computer objects

is stored, next string would help to pull only objects of former type: !(objectclass=computer)

Now you should be looking at something like this:

3

5. Fill in fields of the “Source Backend LDAP servers” tab as follows:

a. “Name”: any descriptive name for this backend connection

b. “Use Anonymous Bind”: not set

c. “Bind DN”: distinguished name of user account being used to access the

server; don’t make a mistake of providing a value in format different

from a distinguished name for it (like, trying to use upn or

sAMAccountName)

d. “Use SSL”: set; pay attention, as it is quite common error to enable SSL

usage, while providing a port in the “Server” field for which SSL/TLS

aren’t enabled (and vice-versa); for AD, TCP port 636 usually

SSL-protected, while TCP 389 is not

e. “Max connections”: 5

f. “Server”: DNS name or ip address of the backend, and a port to use for

4

connection; several server input fields can be added by clicking “Add

server” link, but they all will share the same access credentials and

branches-to-be-searched, so should be used only for adding

fault-tolerance to the configuration; in cause there is a need to define

more than one LDAP server as a different sources of users’ attributes,

additional UI sections can be create by clicking the “Add source LDAP

server” link

g. “Base DN”: DN of a branch within the backend under which search with a

filter, defined in “Customer Backend key/attributes” section, will happen;

several branches may be provided for each backend entry

h. “Enabled”: set; enables this connection; please ignore the fact that this

checkbox becomes unchecked on its own each time your leave the page -

it isn’t because something wrong with the installation, but more like a

harmless issue still existing at the moment of writing (though it won’t

harm to set it again each time you are updating your configuration, just

in case)

i. Now click the “Change Bind Password” link and type in a bind password

for the account chosen as “Bind DN”

After you have completed these steps, the fields on the tab should look like this:

5

6. inum server is used for storing mappings between values of the backend’s key

attribute and values of the unique attribute of the object Gluu uses to store users

internally called “inum”; it’s used in conjunction with the snapshot folder to

detect source attributes that were changed and update all attributes in internal

storage which depend on them. Fill in fields of the “Inum LDAP server” tab as

follows (omit double quotes for values; for Gluu CE package starting from

version 2.4.0 connection to the Gluu’s internal directory will already be

preconfigured on this tab):

a. “Name”: any descriptive name for this inum server connection; it’s

already a good tradition to call it “inumDB”

b. “Bind DN”: distinguished name of user account being used to access the

server; to connect as default admin of the Gluu’s internal storage use

“cn=directory manager”; again, don’t make a mistake of providing a value

in format different from a distinguished name for it

6

c. “Use SSL”: set; remember about a mistake of using wrong port for SSL

connection; for Gluu’s LDAP (which is a modified openDJ directory), TCP

port 1636 usually SSL-protected, while TCP 1389 is not

d. “Max connections”: 5

e. “Server”: DNS name or ip address of your Gluu host, and a port to use for

connection; you are not restricted to the Gluu’s internal LDAP directory,

you can use any already existing in you network for this purpose; several

server input fields can be added by clicking “Add server” link, but they all

will share the same access credentials and branches-to-be-search, so

should be used only for adding fault-tolerance to the configuration

f. “Base DN”: DN of a branch within the inum server under which mappings

are stored; Gluu uses “o=site” for that purpose by default

g. “Enabled”: set; enables this connection; the same issue warning as for the

similar checkbox of the “Source Backend LDAP servers” section applies

h. Now click the “Change Bind Password” link and type in a bind password

for the account chosen as “Bind DN”

After you have completed these steps, the fields on the tab should look like this:

7

7. Fill in fields of the “Cache Refresh” tab as follows (omit double quotes for

values):

a. Select “Copy” from the “Refresh Method” drop-down list; “VDS” option is

intended for very special use cases, ignore it for now

b. Set the “Keep external persons” checkbox; this will preserve default

admin user, as well as any user accounts added by you to the internal

database manually, otherwise they all will be deleted during the first CR’s

pull cycle

c. Leave the “Load source data with limited search” checkbox unset. This

setting can help to further reduce size of a potential response from a

backend by splitting a request of type (key=*) into smaller parts through

subdividing it into a sequence of requests like

(key=aa*),(key=ab*)...(key=a0*),(key=ba*)...(key=a.*)...(key=..*)

d. Leave the “Search size limit” at 1000. This settings sets a limit to how

much entries will be returned in response to one request from a backend.

Many LDAP servers will impose a limitation on how much entires they

8

are ready to send in a response to a single query. LDAP client then can

send the same request again and supply a special cookie token which was

returned to him by the server at the end of the previous request, asking

to send another portion of entries equal to the “Search size limit”

e. Provide mappings for source attributes; the template is

“source_attribute_name -> destination_attribute_name” (or

“attribute_received_from_backend ->

attribute_in_Gluu_internal_storage”); for this example set mappings as

such:

samaccountname -> uid

cn -> cn

sn -> sn

mail -> mail

givenname -> givenname

displayname -> displayname

Below you can find several hints that will help you in your future tasks,

please familiarize yourself with all of them as incorrect settings provided

there become a cause of many issues:

● one source attribute can be mapped to several internal ones

● you must map all attributes you pull from the backend to at least

one attribute of the user objects CR creates in the Gluu’s internal

storage; in case you won’t, CR will assume implicit mapping with

the name of destination (internal) attribute set to be the same as

the name of the source one; that may prevent CR from persisting

all of the pulled attributes, as there (most likely) won’t be

attributes with such names in Gluu’s internal database (though for

some attributes there would be, but relying on this implicit

mapping is strictly not recommended); you can tell something like

that is taking place by spotting records in

oxtrust_cache_refresh.log looking similar to this:

ERROR [gluu.oxtrust.ldap.cache.service.CacheRefreshTimer] (pool-6-thread-8)

Skipping target entries update. Destination server shema doesn't has next attributes:

'[objectcategory]'

9

● there is no need to ensure that all attributes of source objects, for

which mappings were specified, have values assigned to them in a

backend directory; if some of them have not, CR will simply ignore

them when it will be creating/updating internal user objects

● but here is a crucial exception from what is stated in previous

item: you must ensure that your mappings and/or interception

scripts assign values to all attributes that defined as mandatory by

Gluu’s LDAP database’s schema, or CR won’t be able to persist that

user data, too; at the time of writing, for user objects created by CR,

objectclass “person” makes “sn” and “cn” mandatory attributes;

you can tell this has become an issue by spotting records in

oxtrust_cache_refresh.log looking similar to this:

Entry

inum=@!9B99.A9FC.1769.7768!0001!7C38.065C!0000!3499.9F41,ou=people,o=@!9B99.A9F

C.1769.7768!0001!7C38.065C,o=gluu violates the Directory Server schema

configuration because it is missing attribute sn which is required by objectclass

person

● also, please note that when dealing with these mandatory

attributes mentioned in previous item, it’s not anymore enough to

just provide a mapping, you must ensure some values are assigned

to all of them, in the end, as in case when source attributes

mapped to them aren’t assigned some values in a backend

directory, CR won’t be able to just ignore them like it does for

regular attributes; as temporal measure to prevent such source

objects to be pulled and create a lot of error records in logs, you

can specify additional custom LDAP filter clauses using “Custom

LDAP filter” field of the “Customer Backend key/attributes” section,

like this: (sn=*).

Below is an example of [almost] correctly composed attribute mapping

section, based on the set of attributes to pull defined in the “Customer

Backend key/attributes” section before (it’s also provided on the picture

for reference):

10

f. Set “Pooling interval (minutes)” to “1” for this particular exercise

(intervals shorter than 10-15 minutes shouldn’t be used for production

installations as amount of pulled objects may be enormous, what can

place a strain on the backend servers)

g. “Server IP Address”: In a cluster setup you only want the Cache Refresh

process to run on one server, to which all other cluster members will

connect; this settings allows to specify the ip of a master CR server. If you

only have one server, just make sure this attribute is the ip address (i.e.

not a DNS name) on which your Gluu instance is listening for

connections; please also refrain from using “127.0.0.1” or similar

addressess here.

h. “Snapshot Folder”: a directory to which snapshot files containing hashes

of sets of users attributes from backend should be placed; these hashes

are used in conjunction with inum mappings to detect when any of the

pulled attributes has been changed in the backend and thus

corresponding user object needs to be updated in the Gluu’s internal

storage. Hashes are calculated on the set of attributes that were pulled

from the backend according to the list on the “Customer Backend

11

key/attributes” tab, thus any change to this list will invalidate current

hashes and will result in full update of all user objects managed by Cache

Refresh. In Gluu CE versions prior to 2.4.x you must create this directory

by hand; make sure you’ll place it within the file system’s layout of

Gluu’s chroot-ed container, and assign it permissions that will allow

your Gluu instance (i.e. the “tomcat” user) to list its content and

create/modify files there; it’s a good practice to create this directory

under /tmp/; in up-to-date Gluu CE packages default snapshot folder

already exists, and this setting contains a path to it.

i. Set “Snapshots count” to “20”

j. Do not enable Cache Refresh yet! Click the “Update” button to save all

changes, there should be a confirmation that changes are accepted. Check

all tabs and review all settings once more.

k. Enable Cache Refresh feature by selecting “Enable” from “Cache Refresh”

drop-down list and clicking the “Update” button again.

8. Now wait until chosen pooling interval has passed, update the page (it may not

become truly updated by simply pressing F5 button, you may need to move out

of the page and return there again) and verify the counters at the top of it: if CR

is running without issues, they should look similar to provided below (“Updates”

counter should have values other than zero if some objects were changed/added

recently, or if it was the first pulling attempt):

if problems counter keeps its value between pooling cycles, you should

double-check your configuration, and then proceed to the troubleshooting

section of this guide

II. Appoint a new Gluu administrator user.

After completing all steps of this guide you won’t be able to log in with your

default administrative account anymore (see a troubleshooting section on how to

roll-back to the default authentication mode). Gluu’s internal user accounts, created by

Cache Refresh using a data pulled from a backend, aren’t granted with administrative

12

privileges by default, so you will lose ability to manage your Gluu instance via the

oxTrust web UI if you omit this step. To add your backend users to the default

administrators group:

1. Log in to oxTrust as an user with administrative privileges

2. Move to the “Users -> Manage people” page. If everything is working as it

should, you have to be able to lookup users pulled in from your backend using

the search form there by providing their uids (which are equal to their

sAMAccountname-s in our case) or emails. Check attributes of a couple of them

to make sure mappings you set at step 7-e) of the “Configure Cache Refresh” section

produced correct results

3. Move to the “Users -> Manage groups” page and search for key “manager” using

the search form there. Search should return link to the “Gluu Manager Group”

in results. Click the link, and on the group editor’s page add one or more of your

backend users that you want to be granted with administrative access to the

oxTrust web UI from now on

4. Click the “Update” button

III. Configure oxAuth.

The role of oxAuth is to actually perform authentication of local users and to

handle SSO requests coming from remote entities. Even though in this particular use

case the backend will actually be the party which verifies received credentials, oxAuth

will still be actively using internal LDAP storage while following its workflows, for

initial check of user’s in question existence, and, further on, as a final source of

attributes that will be sent to the remote requester. Thus 2 separate LDAP directories

are queried during each user’s login attempt, either of which is irreplaceable piece of

the puzzle. Please check Cache Refresh architecture reference for complete picture.

Follow these steps to configure oxAuth for authentication against your backend

directory (this example will assume that you have configured Cache Refresh as shown

in previous sections):

1. Log in to web UI as an user with administrative privileges

2. Move to the “Configuration -> Manage Authentication” page

3. Fill in fields of the “Manage LDAP Authentication” tab as follows:

a. “Name”: any descriptive name for this backend connection

b. “Bind DN”: distinguished name of user account being used to access the

13

server; don’t make a mistake of providing a value in format different

from a distinguished name for it (like, trying to use upn or

samaccountname)

c. “Use SSL”: set; pay attention, as it is quite common error to enable SSL

usage, while providing a port in the “Server” field for what SSL/TLS aren’t

enabled (and vice-versa); for AD, TCP port 636 usually SSL-protected,

while TCP 389 is not

d. “Max connections”: 5

e. “Server”: DNS name or ip address of the backend, and a port to use for

connection; several server input fields can be added by clicking “Add

server” link, but they all will share the same access credentials and

branches-to-be-searched, so should be used only for adding

fault-tolerance to the configuration

f. “Base DN”: DN of a branch within the backend under which search for

the objects with attribute specified in the “Primary key” input field, will

happen; several branches may be provided

g. “Primary key”: a name of an attribute of object representing user in a

backend which value will be used as login during SSO; will be used in a

search filter to look up user account in a backend under the branch(es)

supplied in “Base DN”, i.e. “(primary_key_name=login_name)”; should be

an indexed attribute; usually it’s the same as the one chosen as “Key

attribute” when configuring Cache Refresh

h. “Local primary key”: a name of an attribute of object representing local

user in the Gluu’s internal LDAP database which value will be used as

login during SSO; will be used in a search filter to look up user account in

the internal database under the branch

“ou=people,o=<org-inum>,o=gluu”, i.e.

“(local_primary_key_name=login_name)” to initially verify that

corresponding user exists, and to acquire a converged list of its attributes

from internal storage

i. “Enabled”: set; enables this connection

j. Now click the “Change Bind Password” link and type in a bind password

for the account chosen as “Bind DN”

k. Click the “Test LDAP connection” button; if you provided correct

combination of host/port/SSL status/bind credentials you will be notified

that connection test has succeeded

4. Leave the “Authentication mode” and “oxTrust authentication mode”

14

drop-down lists at the “Default Authentication Method” tab at “Default”

5. Click the “Update” button

After you have completed these steps, the fields on the tab should look like this:

IV. Completion.

It’s done. Now you can log out from oxTrust web UI and attempt to log in with

credentials of any user which attributes has already been pulled in from the backend

by Cache Refresh. To access administrative features log in with one of the accounts you

appointed as new Gluu administrators in the previous sections of the guide.

15

TROUBLESHOOTING

Configuring Cache Refresh and, subsequently, authentication against LDAP

backend, has proved to be a tricky thing to do. A lot of likely problems usually result

from one of mentioned input fields hasn’t been assigned a value, has been incorrectly

interpreted and assigned a wrong value, or has been assigned a value of correct type,

but in a format it doesn’t expect. The fact that some of such errors won’t clearly

manifest themselves via logs’ records or system notifications doesn’t help

troubleshooting either. Thus you should pay close attention to caveats and hints

provided above and stick to these guidelines as close as it’s possible, at least for your

first several configuration attempts. In case you still are having some issues, your

options are:

1. First of all you must verify that proper network connectivity has been set up.

From your Gluu server’s box check that backend itself, and ports being used to

communicate in LDAP protocol with it, are accessible, and the user account you

are using to bind to it has sufficient permissions to pull all needed data. You

should also make sure that you didn’t make an error of setting “Use SSL”

checkbox while providing a port on which this protocol’s support isn’t enabled,

and vice-versa.

2. Verify that there are actually user objects under specified branches of the

backend, which satisfy query’s filter’s criterias. You can use a command like

provided below to query backend using the same settings and filters you have

chosen for running CR:

/opt/opendj/bin/ldapsearch -h localhost -p 636 -Z -X -D -T "cn=admin, cn=it-staff,dc=example,dc=com" -w

'pass_of_file_w_bindpass’ -b 'cn=SSO-users,dc=example,dc=com' ‘(samaccountname=*)’ dn

samaccountname

3. Now repeat the checks described in 2 previous items for the LDAP server you

configured to be your inum db (Gluu’s internal OpenDJ LDAP directory by

default). CR creates user objects under “ou=people,o=<org-inum>,o=gluu” in

”userRoot” context there. Mappings between objects in a backend and internal

storage are placed under “o=people,o=site” branch of the ”site” context by

default. You can also try to restart Gluu service once to see whether it will help

to resolve your issue, if your environment allows to do that without interrupting

important processes.

4. Incorrectly set snapshot folder is another potential cause of problems. If after

16

some time roughly equal to the chosen CR pulling interval this directory is still

empty - something is definitely wrong. Check that directory exists, tomcat user is

an owner of it, and it has enough permissions to read and write there. In Gluu

CE versions starting from 2.4.0 snapshot directory is created and configured

during setup stage and thus hardly will produce any issues (unless it is changed

by user later on)

5. Check logs for any suspicious messages. You could set CR pulling interval to

some short time span and start monitoring the logs with a command like “tail

-F”. In case of CR you should be particularly interested in

/opt/tomcat/logs/oxtrust_cache_refresh.log, but wrapper.log or oxtrust.log often

can provide some hints, too. Authentication-related issues usually go to the

oxauth.log and /opt/idp/logs/idp-process.log

6. You could switch all your LDAP connections to using unencrypted (“SSL-less”)

connections/ports and monitor the actual LDAP conversations with tools like

wireshark or tcpdump (should be used only as a last resort when suspecting a

bug that results in an incorrect requests sent to a backend/inumdb/internal

storage - when a backend doesn’t provide more convenient ways to monitor

LDAP requests); the other options could be using a transparent LDAP proxy,

though it will require much more efforts to configure it

7. In certain cases you will need to force update of some - or of all - user objects in

the Gluu’s internal directory. One of the ways to achieve that is to remove a

string with inum of the user you need to update from the “inum-snapshot-*.txt”

file in the snapshot folder; to update all users at once just remove the file itself,

or clean the directory. In upcoming updates to oxTrust a GUI control should be

added that would allow to force an update for user objects in internal database

without need to ssh into a remote machine to clean the cache.

8. Sometimes you may also find yourself in situations when you need to remove a

specific internal user object with all mapping data related to it from the Gluu’s

LDAP storage ( if the user to be deleted is the only instance’s administrator at

the moment, you should think about adding another account to default

administrator group while you still have sufficient permissions to do so). To

achieve that, please follow these general steps (you will need some tools capable

to talk in LDAP protocol, like ldapsearch/ldapmodify linux console tools (you can

find them under /opt/opendj/bin/ in the Gluu’s chroot-ed container), or jxplorer

java GUI tool):

17

a. Disable Cache Refresh from web UI by selecting “Disable” from “Cache

Refresh” drop-down list on the “Cache Refresh” tab and clicking the

“Update” button again

b. Using any tool of your choice, find out the said user object under the

branch “ou=people,o=<org-inum>,o=gluu” in the “userRoot” context of

the internal storage, and learn value of its inum attribute

c. Using inum you have found on the previous step, find and remove the

corresponding mapping for this user object under the branch

“ou=people,o=site” in the “site” context of the internal storage

d. Find and remove row containing the inum of the user in the

“inum-snapshot-*.txt” file in the snapshot folder

e. Enable the Cache Refresh again, next pulling should recreate the user

object and all its mappings (if corresponding object in a backend still

exists and nothing prevents CR from creating a new user object in the

internal database)

Just a piece that may become a backup article:

Backup and restore your Gluu instance with tar:

[!] To accomplish this steps you’ll need to be able to access the filesystem/console of

host OS itself when you ssh into the box (i.e. you must NOT be in the Gluu’s chroot-ed

container when you are running these commands)

[!] This method will only backup file system of instance’s container (thus allowing to

restore it if some reconfiguration you have tried broke it). It won’t backup any

configuration outside this file system, like configuration related to the service or

package itself, which are stored in file system of host OS. Consequently, restoring

instance from backup created as described below will be only guaranteed to work for

the same installed package on the very same machine (or the one which is very close to

it, like a cloned vm etc) it was created at (and only if service’s own configuration still

intact; if Gluu CE package was de-installed from the host OS, this method won’t help

you). So it’s mostly a temporal safeguard measure, not a solid long-term solution. Users

are advised to backup whole vm’s/physical box’s volumes that are used by Gluu as a

solid backup approach, including root/system volumes of a host OS.

How to make a complete backup of your instance’s container’s file system:

18

1) Stop Gluu service completely by running this commands from outside of

chroot-ed container: “service gluu-server24 stop” (“service gluu-server stop” for pre-CE 2.4.x

instances); make sure it’s indeed is stopped: “service gluu-server24 status”/“service

gluu-server status” 2) Make sure you have enough free space to store the backup file (a compressed

tar.gz of it may take as much as 1GB+ of disk space for a production server); to

gauge space available at each mounted partition use “df -H” command

3) Run this command to create a backup (it assumes your Gluu is under

“/opt/gluu-server24/”, which is default path for the current CE packages): “tar

-cvpzf /some/path/Gluu_backup_archive.tar.gz --one-file-system /opt/gluu-server24/” and wait until

archiving is completed

How to restore your instance from a complete backup created as shown above:

1) Stop Gluu service of your current instance completely by running this

commands from outside of chroot-ed container: “service gluu-server24 stop” (“service

gluu-server stop” for pre-CE 2.4.x instances); make sure it’s indeed is stopped: “service

gluu-server24 status”/“service gluu-server status” 2) Remove the current file system of your container with “rm -rf /opt/gluu-server24/” (“rm

-rf /opt/gluu-server/” for older CE versions)

3) Make sure you have enough free space to restore previous instance from the

backup file; to gauge space available at each mounted partition use “df -H”

command

4) Run this command to extract if from backup file (it assumes your Gluu service

expects to find file system of its container under “/opt/gluu-server24/”, which is

default path for the current CE packages): “tar -xvpzf

/some/path/Gluu_backup_archive.tar.gz -C / --numeric-owner” and wait until extraction is

completed

19