If the API would be completely documented I could get my work done a lot of
faster so I simply started to document it cause I had to understand it anyway.
I’ve decided to write the documentation with doxygen and put it in the header
file, so that people who use the PAI always have the documentation with them.

After I finished it, started to work on the source code again and got some
things working as I was able to understand the API of the library. Then I
crossed the next undocumented API of a library. Ok, it wasn’t undocumented it
had a text file describing everything but having doxygen documentation is much
nicer than a text file. So I’ve started to document talloc from Samba4 with
doxygen.

The talloc API uses macros for a lot of things to make debugging easier or
to hide things you’re doing from the user. However if you document a macro
than normally you want that it looks like a function. To be able to do that
with doxygen you have to use a little trick. As doxygen has a C preprocessor
built in you can create a define for a doxygen mode. That’s what I’ve done in
the config file and all you need to do in the source code is to use it with
#ifdef.

#ifdef DOXYGEN
/**
* @brief Create a new talloc context.
*
* The talloc() macro is the core of the talloc library. It takes a memory
* context and a type, and returns a pointer to a new area of memory of the
* given type.
*
* The returned pointer is itself a talloc context, so you can use it as the
* context argument to more calls to talloc if you wish.
*
* The returned pointer is a "child" of the supplied context. This means that if
* you talloc_free() the context then the new child disappears as well.
* Alternatively you can free just the child.
*
* @param[in] ctx A talloc context to create a new reference on or NULL to
* create a new top level context.
*
* @param[in] type The type of memory to allocate.
*
* @return A type casted talloc context or NULL on error.
*
* @code
* unsigned int *a, *b;
*
* a = talloc(NULL, unsigned int);
* b = talloc(a, unsigned int);
* @endcode
*
* @see talloc_zero
* @see talloc_array
* @see talloc_steal
* @see talloc_free
*/
void *talloc(const void *ctx, #type);
#else
#define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
void *_talloc(const void *context, size_t size);
#endif


So start to document your API. What you get well be something like this and other will love it!

I’ve introduced a new function to PAM called pam_start_test() which takes and additional argument where you can specify the config directory. After this I’ve changed the call in pamtester and added a commandline option for the config directory. To do automatic testing I’ve added another commandline option to specify the password to use for authentication.

gladiac@maximegalon:~> pamtester -v -C/tmp/pam.d -Psecret login csync authenticate
pamtester: invoking pam_start(login, csync, ...)
pamtester: performing operation - authenticate
pamtester: successfully authenticated

You can find the patches here.

Now the time has come to introduce Roaming Home Directories for Linux. Yesterday I’ve released a new version of csync and the first version of pam_csync. With both components you’re able to use an Active Directory environment to share your data between workstation and notebooks and work offline.

Currently only the SMB protocol is supported but I will write more plugins for other protocols in future. I have sftp and rsync (if doable) in mind. So you will be able to use it at home with you’re small NAS or in a Linux only company environment.

This is not the only use case. If you have a USB disk with your music collection. You can can attach it to PC1 and synchronize it with your local collection. Go to the next computer and synchronize it there again. As csync is a bidirectional file synchronizer the collection on PC1 and PC2 will be the same.

http://www.csync.org/

More at http://www.csync.org/