Upload
others
View
8
Download
0
Embed Size (px)
Citation preview
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