mirror of
https://salsa.debian.org/freeipa-team/freeipa.git
synced 2024-12-25 16:31:08 -06:00
e9ae7c4b89
Introduce a script that configures a local testing environment
with ipa default.conf, krb5.conf, and ca.crt from a server hostname.
The lite server configuration allows easy and convenient testing of
IPA server and client code. It uses an existing 389-DS and KRB5 KDC
server on another machine:
$ contrib/lite-setup.py master.ipa.example
$ source ~/.ipa/activate.sh
(ipaenv) $ kinit username
(ipaenv) $ make lite-server
IPA server UI is available on http://localhost:8888/ipa/
Signed-off-by: Christian Heimes <cheimes@redhat.com>
Reviewed-By: Rob Crittenden <rcritten@redhat.com>
119 lines
3.3 KiB
Markdown
119 lines
3.3 KiB
Markdown
# In-tree development debugging and testing
|
|
|
|
lite-server and lite-client enable fast development, debugging, and
|
|
performance analysis of server or client code from an in-tree source
|
|
directory. The lite-server runs a local web server that uses a remote
|
|
LDAP and KRB5 server.
|
|
|
|
## Prerequisites
|
|
|
|
### Remote IPA server
|
|
|
|
Lite-server and lite-client require a running IPA server. The server
|
|
should have a similar LDAP schema and IPA version as the in-tree
|
|
sources. Some features may not work if the differences are too great.
|
|
|
|
The lite-server only needs a working LDAP server and KRB5 server. For
|
|
KdcProxy or CA-related features the Apache HTTPd and pki-tomcatd service
|
|
must be running, too.
|
|
|
|
If the lite-client is configured for remote-server instead of
|
|
lite-server, then the lite-client uses the HTTP API of the remote
|
|
server.
|
|
|
|
### Local setup
|
|
|
|
1. Configure and build FreeIPA according to ``BUILD.txt``, TL;DR
|
|
|
|
```
|
|
$ sudo dnf builddep -b --spec freeipa.spec.in --best --allowerasing --setopt=install_weak_deps=False
|
|
$ ./autogen.sh
|
|
$ make
|
|
```
|
|
|
|
2. Install additional dependencies for the lite-server
|
|
|
|
```
|
|
sudo dnf install -y python3-werkzeug python3-watchdog
|
|
```
|
|
|
|
3. The FQDN of the remote IPA server must be resolvable. In case the
|
|
server does not have a valid DNS entry, it is possible to add the
|
|
hostname and IP address to ``/etc/hosts``.
|
|
|
|
4. Create configuration files in ``~/.ipa``. The lite-server requires
|
|
an IPA configuration, CA certificate file, KRB5 configuration,
|
|
Kerberos TGT and a file based credential cache. The script
|
|
``contrib/lite-setup.py`` can create a all necessary files for you
|
|
and sets up ``default.conf``, ``krb5.conf``, ``ca.crt``, and
|
|
even ``ldap.conf``:
|
|
|
|
```
|
|
$ contrib/lite-setup.py master.ipa.example
|
|
```
|
|
|
|
5. Setup environment variables: the lite-setup script also creates a
|
|
shell source file that activates a virtualenv like environment. The
|
|
source files sets several environment variables for PATH, KRB5, LDAP,
|
|
IPA, and Python. The env allows you to run the lite server, ``ipa``
|
|
client commands, or OpenLDAP commands:
|
|
|
|
```
|
|
$ source ~/.ipa/activate.sh
|
|
```
|
|
|
|
4. Acquire a TGT
|
|
|
|
```
|
|
(ipaenv) $ kinit username
|
|
```
|
|
|
|
5. Run the lite-server
|
|
|
|
```
|
|
(ipaenv) $ make lite-server
|
|
```
|
|
|
|
6. Run ``ipa`` client commands in another shell session. The lite-setup
|
|
scripts provides a wrapper that uses the development sources, too.
|
|
|
|
```
|
|
$ source ~/.ipa/activate.sh
|
|
(ipaenv) $ which ipa
|
|
~/.ipa/ipa
|
|
(ipaenv) $ ipa ping
|
|
```
|
|
|
|
7. Deactivate the environment
|
|
|
|
```
|
|
(ipaenv) $ deactivate_ipaenv
|
|
```
|
|
|
|
## Limitations
|
|
|
|
The lite-server does not have access to the ra-agent certificate.
|
|
Therefore most CA and KRA (vault) operations are not supported.
|
|
|
|
## Tricks and tips
|
|
|
|
The lite-server has a functional Web UI at
|
|
http://localhost:8888/ipa/xml. The session is already authenticated
|
|
with the current TGT.
|
|
|
|
The lite-setup script has additional options
|
|
|
|
* ``--kdcproxy`` configures ``krb5.conf`` for Kerberos over HTTPS
|
|
* ``--debug`` enables IPA and KRB5 debugging
|
|
* ``--remote-server`` lets you run local client commands without a
|
|
local lite-server.
|
|
|
|
The ``make lite-server`` command supports arguments like
|
|
``PYTHON=/path/to/custom/interpreter`` or
|
|
``LITESERVER_ARGS='--enable-profiler=-'``.
|
|
|
|
By default the dev server supports HTTP only. To switch to HTTPS, you
|
|
can put a PEM file at ~/.ipa/lite.pem. The PEM file must contain a
|
|
server certificate, its unencrypted private key and intermediate chain
|
|
certs (if applicable).
|