diff --git a/README.md b/README.md
new file mode 100644
index 0000000..201b5c9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# mxshadow
+
+This installs:
+
+* /lib/libnss_mxshadow.so.2 : nss service to query shadow entres via TLS from a server
+* /usr/sbin/mxshadowsrv : The server
+
+At runtime, the nss service needs these files:
+
+* /etc/mxshadow.conf : Configuration file containing server address and port
+* /etc/mxshadow.cert.pem :  Certificate to verify the server
+
+The format of the configuration file is
+~~~
+# address and port of mxshadow server
+
+server = 141.14.16.131
+port = 872
+~~~
+
+At runtime, the server needs the vetificate file and the related key file. These are specified via its command line:
+
+    mxshadowserv --key-file FILENAME --cert-file FILENAME [--address ADDRESS] [--port PORT} SHADOW-FILEANME
+
+Additionally, the source package contains these tools, which are build but not installed:
+
+* create-key.sh : Shell script to create key and certificat for the server
+* test_server : Standalone program to query the server ( usage: test_server username )
+* test_query_shadow: Standalone program to test getspan (usage: test_query_shadow username )
+
+# Mariux:
+
+* This package is installed from a bee file
+* The key an cert files have been generated with `create-key.sh`
+* `/etc/mxshadow.conf` and `/etc/mxshadow.cert.pem` are installed from mxtools.
+* A systemd service unit `/etc/systemd/system/mxshadow.service` to run the server is also intalled from mxtools.
+* The Makefile in `/package/nis/src` generates a shadow map `/package/nis/var/shadow`
+* The key and vertificate files for the server are stored in /package/nis/etc/
+
+## Password authentication overview
+
+1. Tools like login, su or sshd which want to do password authentication, use the PAM library. See pam(8).
+2. pam reads config files, e.g. `/etc/pamd.d/sshd`
+3. These file deletegate to pam module plugins. E.g. with `auth required pam_unix.so`
+4. `pam_unix.so` uses `getpwent()` and `getspent()` from glibc.
+5. glibc reads the configuration file `/etc/nsswitch.conf`
+6. This file delegates to nss service providers, e.g. `shadow: files mxshadow` for `libnss_files.so.2` and `libnss_mxshadow.so.2`
+