This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License. To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/3.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
1.1. What is Libki?
Libki is a Free Open Source cross-platform pc reservation booking and time management system designed to allow time limited access to computers on a network. Libki is ideally suited for use in locations where a controlled computing environment is paramount such as public access systems, libraries, school computer laboratories and more! It consists of two parts, the Libki server, and the Libki client.
Learn more about Libki by visiting the official Libki website, libki.org.
1.1.1. The Libki server
The Libki server utilizes a web-based administration system that can be accessed from any networked pc via a web browser. From the web administration one can create and delete users, change the amount of time left on an account, send or leave a message for a user, log out and/or ban users, and see which client computers are available and which are currently being used. In addition, the system has a public web interface for viewing which kiosks are available, which are unavailable, and to allow the placing of reservations.
1.1.2. The Libki client
The Libki client is cross-platform and runs on many operating systems including Microsoft Windows and Linux. The Libki client features a counter to let the user know how many minutes are left, and the ability to log off early. Any unused minutes can be used at any other computer running the Libki client. The Libki client can be set to log off from the operating system, or even reboot the computer when a user logs off from the Libki client.
1.2. Libki server recommendations
Guides for deployment are available in the Installation section.
Libki Server is meant to work on all web browsers, but is most tested on Chrome and Firefox.
1.3. Making contributions
This manual is an ever-changing document and edits to the manual are welcome at any time. The canonical source for the Libki manual is https://github.com/Libki/libki-manual
If you have a suggestions or contribution for the manual, please follow the guidelines for contributing to the Manual.
2.1. Automatic installation
When using the automatic installer, the server must be Ubuntu Server 18.04 or Debian Stretch.
Please read through the installation moments. There is a one-line command in the end if that’s what you prefer.
2.1.1. Login as root
If you are not logged in as root, switch to root.
2.1.2. Updating, upgrading and installing git
It’s always best to do a fresh upgrade to be sure you have the latest versions of software available.
Git is used to download the Libki server.
apt update && apt upgrade -y && apt install git -y
2.1.3. Downloading and running the installer
First download the Libki server.
git clone https://github.com/libki/libki-server.git
Enter the downloaded directory.
Run the installer.
2.1.4. One-line installer
This is the whole installation process in one single line.
apt update && apt upgrade -y && apt install git && git clone https://github.com/libki/libki-server.git && cd libki-server && ./install.sh
2.2. Manual installation
If you wish to completely build the Libki server by yourself, these guidelines should help you along the way. This is written towards someone new to terminal and a lack of GUI.
First of all, update and upgrade.
apt update && apt upgrade -y
apt install cpanm curl perl git make build-essential unzip mysql-server ntp -y
You might need these packages too, depending on your server. If you encounter error messages when installing the needed perl modules, this is the place to start.
apt install libmysqlclient-dev libxml-parser-perl libxml-libxml-perl
2.2.2. Setting up a user
It is suggested to setup a new user account to run the server from. From here on, we’ll use the username libki. Give it a good, strong (and preferrably memorable) password.
2.2.3. Clone the repository
Clone the repo to the home directory of your newly created user.
git clone https://github.com/libki/libki-server.git /home/libki/libki-server
2.2.4. Install needed perl modules
cd /home/libki/libki-server cpanm -n --installdeps .
This will take a while. Make sure it ends with saying everything was installed correctly. If not, you will need to fix what’s missing.
Now we need to add the Libki server’s perl module to our $PATH, so our shell knows where to find it.
echo "export PERL5LIB=$PERL5LIB:/home/libki/libki-server/lib" >> ~/.bashrc
We also need to add it to the libki user’s $PATH.
echo "export PERL5LIB=$PERL5LIB:/home/libki/libki-server/lib" >> /home/libki/.bashrc
2.2.5. Create a database
Depending on your MySQL or MariaDB version, it may or may not want you to log in with a username and password. If you are to log in with a username and password, the username is root and you chose the password during the dependencies installation.
If that’s the case, start MySQL with
mysql -uroot -p.
If you didn’t get to create a root password during installation, just start MySQL with
Once inside MySQL, we need to create a database and a user. Note that all aphostrophes are essential and cannot be omitted.
CREATE DATABASE libki; CREATE USER 'libki'@'localhost' IDENTIFIED BY 'CHOOSEAPASSWORD'; GRANT ALL PRIVILEGES ON libki.* TO 'libki'@'localhost'; FLUSH PRIVILEGES; EXIT;
2.2.6. Populate the database and create an admin account
We got our perl modules, we have an empty database… Let’s fill it with things.
In order for Libki to access the database, we must give it the login information. Make a copy of the libki_local.conf.example file and remove .example. Open it and change the password to the one you chose.
cp libki_local.conf.example libki_local.conf nano libki_local.conf
You save and close with Ctrl-O and Ctrl-X, respectively.
Now create an admin account, so we can access the administration pages once the server is up and running.
./script/administration/create_user.pl -u ADMINUSERNAME -p ADMINPASSWORD -s
2.2.7. Setting up log files
The Libki server will produce log files. Their default location is /var/log/libki. Even if you don’t want to change the default location, you still need to make a working copy the log4perl.conf.example file.
cp log4perl.conf.example log4perl.conf
2.2.8. Installing cron jobs
Part of what makes the Libki server tick is scheduled jobs called cron jobs.
./script/cronjobs/libki.pl is the timer and
./script/cronjobs/libki_nightly.pl is the cleaner that resets everything overnight.
There are two pre-written cron files, just to import. The first one is for the libki user and the second one for root.
cat installer/cron/libkicron | crontab -u libki - cat installer/cron/rootcron | crontab -
2.2.9. Create a Libki service
Copy the init template to /etc/init.d.
cp init-script-template /etc/init.d/libki
If you want to edit the port of the server (if you, for example, want to run it on port 80 and don’t want to use a reverse proxy), this is the time. Open it up, change port number from 3000 to 80 (or something else), save and close.
Finally, run update-rc.d to enable Libki as a service.
update-rc.d libki defaults
2.2.10. Start the server
service libki start
If all went well, you should have a server up and running by now. You can visit it on http://127.0.0.1:3000/administration.
2.2.11. Manual install optional: Set up your reverse proxy
Make sure you’re logged in as root.
apt-get install apache2
Navigate to the libki-server directory
Run the apache_setup.sh script
This disables the old default conf, copies reverse_proxy.config to Apache’s folder and enables both the Libki reverse proxy and the needed modules..
service apache2 restart
You can now test to see if your server is running by using the cli web browser 'links'. If you don’t have links installed you can installed it via the command
sudo apt-get install links
Now, open the Libki public page via:
If this loads the Libki login page, congrats! If you get an error, you can try bypassing the proxy and access the server directly on port 3000.
If this works, then you’ll want to check your Apache error logs for the failure reason. If it does not work, you’ll want to check the Libki server error log instead. It can be found at /home/libki/libki\_server.log if you’ve followed this tutorial closely.
3.1.1. Basic settings
Default time allowance per day
This setting determines the total number of minutes a user will have for the day by default.
|The value of Default time allowance per day should be a whole number.|
Default time allowance per session
This setting determines the total number of minutes a user will have for each session per day. So, if a system is configured with 120 minutes time allowance per day, and 30 minutes time allowance per sessions, a user will be able to log in 4 times per day for 30 minutes at a time.
|The value of Default time allowance per session should be a whole number.|
Default guest time allowance per day
This is the same as Default time allowance per day, except for guest accounts instead of regular users.
|The value of Default time allowance per day should be a whole number.|
Default guest time allowance per session
This is the same as Default time allowance per session, except for guest accounts instead of regular users.
|The value of Default guest time allowance per day should be a whole number.|
Client registration update delay limit
When a Libki client launches, it periodically connects to the Libki server to register itself. If a client does not re-register itself within this number of minutes, the Libki server will remove it from the list of active clients.
|The value of Client registration update delay limit should be a whole number.|
3.1.2. Data retention
This setting controls how long user and client data is retained in an un-anonymized format. If this setting is left empty, the data will be kept indefinitely.
When anonymized, a particular user will be given a new random id on a per-day basis. In this way, statistics will still be able to track usage on a per-user basis per day, but will be unable to track per-user usage over any longer time period.
|The value of History anonymization should a whole number.|
This setting controls how long user and client data is retained for the purpose of generating statistics and checking usage history, in days. If this setting is left empty, the data will be kept indefinitely.
|The value of History retention should a whole number.|
Inactive user retention
This setting controls how long a user can be inactive before being automatically deleted, in days. If this setting is left empty, all users will be kept indefinitely.
|The value of Inactive user retention should be a whole number.|
This setting should be used to conform to GDPR if necessary.
3.1.3. Client behavior
This setting controls how clients may be used by users. There are three possibilities.
First come, first served.
Allows a patron to log in to any client not currently being used.
Requires a patron to place a reservation for a client before logging in to it.
First come first served, with option to place reservation.
A hybrid approach that allows patrons to log in to any client that is not currently in use or reserved.
|The setting Display usernames controls if the user’s username is displayed on the reserved client computer.|
The amount of time \( in minutes \) that a user has to log into his or her reserved computer. If the user does not log in within the specified time limit, the reserved client will become available again.
|The value of Reservation timeout should be a whole number.|
This setting determines if a Libki client that is reserved and waiting will display the username of the person it is waiting for.
3.1.5. Automatic time extension
Libki has an automatic time extension system that allows users to remain logged into a client computer beyond the pre-determined number of minutes per session a user is allotted.
The amount of time to automatically increase a user’s session time by \( in minutes \).
|The value of Extension length should be a whole number.|
Extend time at
This setting controls at what point in time an extension length is triggered. A session will be extended when the user’s session time drops below this number, in minutes.
|The value of Extend time at should be a whole number.|
Extend time unless
This setting determines if a user is eligible for an automatic time extension. It has two options:
User’s client is reserved
This choice prevents a time extension in the case that the user’s client is reserved. Reservations for other client’s are not taken into account.
Any client is reserved
This choice prevents a time extension in the case that any client is currently reserved. If any client is reserved a time extension will not take place, even if the users’s client is not currently reserved,
When extending time
This setting determines how minutes are added to a patron’s account when an automatic time extension occurs. It has two options:
Take minutes from daily allotment
This options moves minutes from the user’s daily allotment of minutes to the user’s session minutes. That means the user can continue using the client computer, but only up to his or her daily allotment of time.
Don’t take minutes from daily allotment
This option adds minutes to a users session "out of thin air". As such, it does not effect how many sessions a user will have per day.
Terms of service
This setting allows a library to add terms of service for use of computers running the Libki client. Simply adding text of your terms of service in the textbox will cause the terms to be displayed to any person logging into a Libki client. If the person chooses yes the login will proceed as usual. If the person chooses no the login screen will be reset.
Client login banners
The client banners are optional areas on the top and bottom of the Libki client login screen. They are functionally like to web browsers. As such, anything that is viewable in a web browser is viewable in the banner areas \( size permitting \).
The URL for the image or html that you wish to display in the banner section.
If the Source URL is an image, it can be forced to a specific width instead of using the image’s actual width. Leave empty to use the image’s actual width.
This is the same as Width for the Source URL but for height.
3.1.6. Guest passes
Prefix for guest passes
The phrase that each guest pass username should start with. If left empty, the phrase "guest" will be used ( e.g. guest1, guest2, guest3, etc ).
|This setting can be a word or short phrase, but should contain only letters and numbers. Avoid using spaces or special characters.|
Passes to create per batch
If the Multiple guests button is used, this setting will control how many guest accounts are generated with each clock.
|The value of Passes to create per batch should be a whole number.|
The text in this field will be prepended to the guest username, ( e.g. "Username:" ).
This setting works the same as Username label but for the generated password instead of the username.
3.1.7. ILS integration
Entering a url here will cause the username in the user’s table of the web administration to become a hyperlink with the user’s username at the end. For example, http://catalog.koha.library/cgi-bin/koha/members/member.pl?quicksearch=1&searchmember= will link to the Koha ILS’s search function for the given username.
Single Sign-on can with an ILS can be achieved via SIP2. Settings for the ILS SIP2 server can be stored in the libki\_local.conf file or the SIP configuration setting.
To enable SIP authentication, you will need to edit your libki_local.conf and add a section like this:
<SIP> enable 1 host ils.mylibrary.org port 6001 location LIB username libki_sipuser password PassW0rd terminator CR require_sip_auth 0 enable_split_messages 0 no_password_check 0 (1) fee_limit 5.00 (2) deny_on charge_privileges_denied (3) deny_on recall_privileges_denied (4) deny_on excessive_outstanding_fines (5) deny_on_field AB:This is the reason we are denying you (6) </SIP>
|1||If enabled, Libki won’t validate the password given against the SIP server, any password will work|
|2||Can be either a fee amount, or a SIP2 field that defines the fee limit ( e.g. CC ), delete for no fee limit|
|3||You can set SIP2 patron status flags which will deny patrons the ability to log in|
|4||You can set as many or as few as you want. Delete these if you don’t want to deny patrons.|
|5||The full listing is defined in the SIP2 protocol specification|
|6||You can require arbitrary SIP fields to have a value of Y for patrons to be allowed to log in. The format of the setting is <Field>:<Message>.|
An equivilent configuration set via YAML in the system settings would look like this:
enable: 1 host: ils.mylibrary.org port: 6001 location: LIB username: libki_sipuser password: PassW0rd terminator: CR require_sip_auth: 0 enable_split_messages: 0 fee_limit: 5.00 deny_on: - charge_privileges_denied - recall_privileges_denied - excessive_outstanding_fines deny_on_field: "AB:This is the reason we are denying you"
The SIP section requires the following parameters:
enable: Set to 1 to enable SIP auth, 0 to disable it.
host: The SIP server’s IP or FQDN.
port: The port that SIP server listens on.
location: The SIP location code that matches the sip login.
username: The username for the SIP account to use for transactions.
password: The password for the SIP accouant to use for transactions.
terminator: This is either CR or CRLF depending on the SIP server. Default is CR
require_sip_auth: Does this SIP server require a message 93 login before it can be used? If so this should be set to 1 and the username/password fields should be populated. This should be set to 1 for Koha.
enable_split_message: IF thie server supports split messages you can enable this. This should be set to 0 for Koha.
fee_limit: As notated, this can be a set number or a SIP field to check. If the fee limit is exceeded, the user login will be denied.
deny_on: This can be repeated to deny logins based on the patron information flags detailed in the SIP2 protocol specification.
deny_on_field: This can be repeated to deny logins if the Specified field does not have a value of "Y". ==== LDAP
Single Sign-on with other systems can be achieved via LDAP. Settings for LDAP server are currently stored in the libki\_local.conf only, though setting support is expected soon.
|Make sure the URL beings with http:// or https:// as necessary.|
3.2. Closing hours
Closing hours are a way to prevent users from starting a session that will be cut short by the closing of the location he or she is at. Closing hours can be set on a site-wide basis, or on a per-location basis. If a given location has no closing hours set, that location will use the All locations closing hours.
3.3. Print management
Print management in Libki is powered by Google Cloud Print. To set up print management, first set up your printers in Google Cloud Print. Next, generate a client id and secret. Finally, enter your configuration in the Printer configuration setting as YAML. The code block below is an example configuration with two printer profiles for a single printer ( one color, one monochrome ).
3.3.1. Finding your cloud printer id:
Set up the printer for Google Cloud Print
Use the Printer Search API to search for you printers, or browse to https://www.google.com/cloudprint/search directly
Locate your printer in the results, find the "id" field, it should look something like
3.3.2. Getting your client id and client secret
Get oAuth2 Credentials
Browse to https://console.developers.google.com/
Enable Cloud API
Create credentials for OAuth 2 type=“Other”
Save the ID and secret for use in the Libki print configuration
3.3.3. Setting up your print management configuration
You can use the configuration below as a template, simply replace the
google_cloud_id field values with your own.
Note the example has two instances of the same printer installed, one for printing in color, and one for monochrome.
google_cloud_print: client_id: 893746288161-libc4aj9loitf5i2lcuuonj6ggqb37uc.apps.googleusercontent.com client_secret: dEjNmggj-PS9_LnvP92jIYu3 printers: color: type: google_cloud_print google_cloud_id: d4355eb9-5b5b-3982-1492-9a1245298409 name: color ticket: color: type: STANDARD_COLOR monochrome: type: google_cloud_print google_cloud_id: d4355eb9-5b5b-3982-1492-9a1245298409 name: monochrome ticket: color: type: STANDARD_MONOCHROME
3.3.4. Authorizing your server to use the Cloud Print API
Open the URL given in a web browser
Authorize your account
Copy and paste the code you are given back into the script
You should recieve the message
Session stored.if everything was successful.
3.3.5. Configuring your clients
After you’ve set up your server for print management, you will then need to configure your clients as well.
To accomplish this, you must edit the
Libki Kiosk Management System.ini file.
On Windows operating systems, this file is most often located in
C:\ProgramData\Libki but may be located elsewhere depending on your specific OS configuration.
You will most likely need to edit this file as an Administrator.
Once you have located the file, you will need to add a new configuration block to the bottom.
[printers] color="C:\\printers\\color" monochrome="C:\\printers\\monochrome"
As you can see, the printers match the
name: fields defined print management configuration for the server.
You will also need to ensure those directories exist on the client computer.
Once the Libki client has been started, it will watch those directories for PDF files.
When the client sees a file, it will uploaded it to the server with the matching printer name.
You can use any PDF print driver to print PDF file to these directories. A custom PDF print driver for Libki is in development, but not yet available.
4.1. Statistics & history
5. Desktop client
The Windows wizard installer for the Libki client can be downloaded from https://github.com/Libki/libki-client/releases
Make sure to download the client version that matches your Libki server version.
5.2. Installer wizard
After downloading the client, run it and you will be presented with the installer wizard. Here you will be asked a series of questions about how you would like your client to be configured.
Set this field to
https if you have set up your Libki server behind an SSL-enabled proxy,
set it to
Set this to the ip address or FQDN for your Libki server.
Set this field to the external port your Libki server is listening on.
Set this field to the location you wish to label this client as being at. This is an arbitrary text field. If you are setting multiple clients to have the same location, make sure that you use the exact same spelling for all the clients.
For example, you may set the location to
Main Floor or
5.2.5. Run only for this user
If you enter a Windows account username in this field, the Libki client will only launch when that Windows user is logged in to.
5.2.6. Run for all users but this one
This is the inverse of
Run only for this user. If you set a Windows account username
in this field, the client will not run for that user, but will for all other users.
5.2.7. Client name
Here you can name this client node, each client should have a unique username otherwise you will get unexpected behavior.
If you leave this field blank, Libki will user the client computers hostname as the Libki client’s name.
If you set the value of this field to
OS_USERNAME, the logged in Windows account username
will be used as the client’s name.
5.2.8. Logout action
This section will let you choose what happens when the Libki client logs out, either because the patron’s time has run out, or the patron chooses to log out early.
Log out of operating system
This option will trigger a logout of the Windows account that the client is currently logged in as. This is useful when combined with the software Clean Slate, which resets the state of a computer each time that the Windows account is logged out.
This option leaves the host OS in the state it is currently in, and merely redisplays the login screen. This option is not recommended for production use. Any applications the user had open at the time the client was logged off of will still be open. This option is useful for testing and debugging.
5.2.9. Client disable password
Here you may enter a 'back door' password. At any time, if this password is entered into the Libki login screen with an empty username, it will cause the Libki client to close. This is useful in the event that a client loses connectivity with the server and is unable to verify logins.
5.2.10. Installation location
This is the path to which the Libki client will be installed. It is recommended to use the default installation path unless you have a specific reason to do otherwise.
5.3. Configuration options
The Libki client may be customized further with options set in the configuration INI file that are not revealed in the installer wizard.
To modify the labels on the Libki login screen, you can set a
[label] block. There valid options are:
You need only add lines to the
[label] block for the labels you wish to modify. Any labels not redefined here will use the default word or words for
the given language in use.
[labels] username="Username:" ; What text it will say at the username input field password="Password:" ; What text it will say at the password input field waiting_holds="You have holds waiting." ; This can be used if your client connects to your library's ILS via SIP2.
5.3.2. Passwordless login
If you are using single-signon via SIP, and your SIP server is set to mark any password a users provides as valid, you can set the Libki client to passwordless mode.
To do so, simply add or modify the
no_passwords key under the
[node] section to appear like so:
no_passwords=1 ; Lets you hide the password field if passwords are not used.
5.3.3. restrict client usage by age
It is possible to specify that a given Libki client can only be used by persons of a given age range.
To use this feature, just add a new key under the
[node] section of the Libki client ini named
This feature only works when using single-signon via SIP, and the SIP server returns a
PB field of the date format
YYYYMMDD where that date is the patron’s date of birth.
This will limit the client to patrons older than 18. At the moment this only works via SIP2 as there is currently no way to edit a user’s age from the staff administration.
Multiple age limits can be implemented delimited by commans, such as
age_limit="ge11,le17" which will limit the client to users between ( and including ) the ages of 11 and 17.
The format first two characters are the comparison. Supported comparisons are:
eq: equal to
ne: not equal to
lt: less than
gt: greater than
le: less than or equal to
ge: greater than or equal to
It is possible to make a client unusable by anyone ( e.g. "gt18,lt17" ) so be careful with this configuration.
6. Backup & restoration
|It is HIGHLY advised to only perform backups and restorations of the database while the system is not being used!|
6.1. Backing up
The backup program is intended to be used on a server with a libki user.
A backup folder will be created in the libki user’s home directory, where the backups are stored.
Please note that this will only create local backups. It is adviced to transfer them to a safe location. A guide on how to transfer automatic backups to an FTP server will be added later.
6.1.1. Make a backup manually
The backup will be created and stored in
/home/libki/backups. The file name will contain date and time for the backup for easier identifying, i. e.
6.1.2. Make automatic backups
The backup program features a silent mode, perfect for when you don’t want any user input or text output. Run
libki-backup -s to run it in silent mode.
Automatic backups work the same way as the manual backups, but does not provide any output text. The backup file is created directly in
If you want to make backups automatically according to a schedule, this is easiest done through crontab. I won’t go through how crontab works, but will provide some example schedules.
Start by running
crontab -e. You will probably want to use the default editor. Add the schedule at the bottom of the file.
Daily backup at 02:00:
0 2 * * * /usr/local/bin/libki-backup -s
Backup every Sunday evening:
0 21 * * SUN /usr/local/bin/libki-backup -s
Backup the first date in every month at 01.15:
15 1 1 * * /usr/local/bin/libki-backup -s
6.2. Restoring a backup
Restoring a backup of the database will delete the current database, so be sure you really want to do this.
Start by navigating to the folder containing the backup you want to restore. If the backup was created with the backup program, this folder will be
Now run the program and specify what backup you want to restore.
Your database is now at the point it was when the backup was created.
7.1. Client & server
7.1.1. Submitting bug fixes and features
File an Issue on GitHub in the matching repository ( client, server, manual, etc… ) for the issue ( for both enhancement and bug fixes )
The earlier you file the better. It’s much better to file an issue stating your intention to develop a new feature or fix before you start to give other community members a chance to review the issue and give feedback.
The subject line of your commit(s) should begin with "Issue XX: " followed by the description of what the patch does.
Include a hyperlink to the GitHub issue this patch resolves.
GitHub will notice and automatically link the commit to the issue.
Pull requests for features and fixes to the Libki server should be submitting as pull requests via the Libki server GitHub repository.
Pull requests for features and fixes to the Libki client should be submitting as pull requests via the Libki client GitHub repository.
7.1.2. Coding guidelines
Server coding guidelines
Perltidy new or altered pieces of code before submission.
Libki server comes with a .perltidyrc file that should always be used when tidying Libki server code.