libravatarserv is a simple libravatar server. It is intended to be used as a CGI program.
Libravatar is a free service and an open specification for hosting profile images tied to email or OpenID addresses.
The default branch changed from
main on 2022-06-11.
- Avatar delivery based on email addresses
- Default avatar for unknown addresses
- MD5 hashes
- SHA256 hashes
- Variable image size (
- Default fallbacks (
default): 404, mp/mm, identicon (=retro), retro
- Requesting file type by appending
.webpto the hash
The API is explained in greater detail at the Libravar wiki.
- Because it isn't possible to store filenames with '/' in it on most filesystems.
- The default fallbacks monsterid, wavatar, robohash and pagan
- Patches welcome
- Fallback URLs for to external sites (due to CWE-601)
- We have a server setting (
LIBRAVATARSERV_REDIRECT) to redirect to libravatar.org.
- We have a server setting (
Install nginx and fcgiwrap, copy the example config to the nginx configuration directory and edit it according to your needs. Other webservers and cgi spawners will also work, of course.
Add the following DNS records to your nameserver:
_avatars._tcp.example.com. IN SRV 0 0 80 avatars.example.com _avatars-sec._tcp.example.com. IN SRV 0 0 443 avatars.example.com
_avatars._tcp.example.com is for HTTP,
_avatars-sec._tcp.example.com is for
libravatarserv looks in the current working directory for images. You can force
a different directory by setting the environment variable
LIBRAVATARSERV_DIR. Any file format supported by ImageMagick is supported, but
it should be PNG, JPEG or GIF for compatibility.
The image files are named like your email address, no file extension. The
default behaviour for unknown users is to return a 404 error. You can change
that by setting the environment variable
any value accepted by
default. If you want to force a default image for
unknown email addresses, name it
default. The default image overrides the
specified fallback in the URL and in the environment variable.
If you want to support "Mystery persons" (mp/mm) as default avatars, place a
mp in the avatar dir. You can use the
default libravatar mystery person
Test your setup on https://www.libravatar.org/tools/check/.
The avatar directory could look like this:
/var/db/libravatarserv ├── [ 32K] default ├── [ 759] firstname.lastname@example.org └── [ 16] email@example.com -> firstname.lastname@example.org
Configuration is done through environment variables.
The directory containing the avatars.
Default: current directory
Controls what happens if no fallback was requested.
Possible values: Anything that can be supplied with the
Set to 1 to redirect to libravatar.org if the user is not found.
Things to keep in mind
libravatarserv resizes images on the fly and potentially calculates hashes for every user on every request. This could seriously strain the ressources of your computer if many users use the service. Make sure to set up caching if you expect more than occasional traffic.
Gentoo ebuilds are available via my repository.
- C++ compiler (tested: gcc 8/11, clang 7)
- cmake (at least 3.12)
- crypto++ (tested: 8.6 / 5.6)
- imagemagick (tested: 7.1 / 6.7)
- identiconpp (at least: 0.7.1)
On a Debian system, install the packages:
build-essential pkg-config cmake libcrypto++-dev libmagick++-dev and
identiconpp (or use the bundled).
cmake -S . -B build cmake --build build
-DCMAKE_BUILD_TYPE=Debugfor a debug build
-DLIBRAVATAR_BUNDLED_IDENTICONPP=YESto use the bundled identiconpp
To install, run
sudo cmake --install build. To create a linux distribution
cpack -G DEB or
cpack -G RPM.
Contributions are always welcome. You can submit them as pull requests or via
Tests on a laptop with an x86_64 2GHz CPU with 2 cores showed that the average response time is 140ms with 3 avatars in the "database", 180ms with 1003 avatars. The tests were done with a 27KiB image, scaled down from 569px to 512px. It took 3,8s / 5-7s to transfer 50 unique avatars (about 3 KiB each) on one page.
This test was done on an older version and may not be accurate any more.