diff --git a/NEWS b/NEWS
index d9bb5ad6..f85d4229 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,7 @@
 xbps-0.42 (???):
 
+ * xbps.d(5): new manual page detailing the configuration settings.
+
  * xbps-dgraph(8): added support to generate dependency graphs, repository
    mode, prints results to stdout, supports most of the options available
    in other utils, etc. This is now a first class utility.
diff --git a/bin/xbps-checkvers/xbps-checkvers.8 b/bin/xbps-checkvers/xbps-checkvers.8
index e97a0b73..fe27be87 100644
--- a/bin/xbps-checkvers/xbps-checkvers.8
+++ b/bin/xbps-checkvers/xbps-checkvers.8
@@ -1,4 +1,4 @@
-.Dd November 5, 2014
+.Dd December 9, 2014
 .Dt XBPS-CHECKVERS 8
 .Sh NAME
 .Nm xbps-checkvers
@@ -49,6 +49,7 @@ tree.
 Shows the XBPS version.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
 .Xr xbps-install 8 ,
diff --git a/bin/xbps-create/xbps-create.8 b/bin/xbps-create/xbps-create.8
index e0004713..8dbe665f 100644
--- a/bin/xbps-create/xbps-create.8
+++ b/bin/xbps-create/xbps-create.8
@@ -1,4 +1,4 @@
-.Dd September 30, 2014
+.Dd December 9, 2014
 .Dt XBPS-CREATE 8
 .Sh NAME
 .Nm xbps-create
@@ -82,6 +82,7 @@ A list of required shared libraries, separated by whitespaces. Example:
 .Ar 'libz.so.1 libfoo.so.2' .
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-dgraph 8 ,
 .Xr xbps-install 8 ,
diff --git a/bin/xbps-dgraph/xbps-dgraph.8 b/bin/xbps-dgraph/xbps-dgraph.8
index 87b0811f..23059ed1 100644
--- a/bin/xbps-dgraph/xbps-dgraph.8
+++ b/bin/xbps-dgraph/xbps-dgraph.8
@@ -1,4 +1,4 @@
-.Dd November 27, 2014
+.Dd December 9, 2014
 .Dt XBPS-DGRAPH 8
 .Sh NAME
 .Nm xbps-dgraph
@@ -120,6 +120,7 @@ Default package database (0.38 format). Keeps track of installed packages and pr
 Default cache directory to store downloaded binary packages.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-install 8 ,
diff --git a/bin/xbps-install/xbps-install.8 b/bin/xbps-install/xbps-install.8
index efff9ff1..7d8271e8 100644
--- a/bin/xbps-install/xbps-install.8
+++ b/bin/xbps-install/xbps-install.8
@@ -1,4 +1,4 @@
-.Dd December 6, 2014
+.Dd December 9, 2014
 .Dt XBPS-INSTALL 8
 .Sh NAME
 .Nm xbps-install
@@ -140,6 +140,7 @@ Default package database (0.38 format). Keeps track of installed packages and pr
 Default cache directory to store downloaded binary packages.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/bin/xbps-pkgdb/xbps-pkgdb.8 b/bin/xbps-pkgdb/xbps-pkgdb.8
index dbaf5ecc..6fdee891 100644
--- a/bin/xbps-pkgdb/xbps-pkgdb.8
+++ b/bin/xbps-pkgdb/xbps-pkgdb.8
@@ -1,4 +1,4 @@
-.Dd November 5, 2014
+.Dd December 9, 2014
 .Dt XBPS-PKGDB 8
 .Sh NAME
 .Nm xbps-pkgdb
@@ -79,6 +79,7 @@ Default package database (0.38 format). Keeps track of installed packages and pr
 Default cache directory to store downloaded binary packages.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/bin/xbps-query/xbps-query.8 b/bin/xbps-query/xbps-query.8
index 125fede5..217e3b5f 100644
--- a/bin/xbps-query/xbps-query.8
+++ b/bin/xbps-query/xbps-query.8
@@ -1,4 +1,4 @@
-.Dd December 6, 2014
+.Dd December 9, 2014
 .Dt XBPS-QUERY 8
 .Sh NAME
 .Nm xbps-query
@@ -259,6 +259,7 @@ Default package database (0.38 format). Keeps track of installed packages and pr
 Default cache directory to store downloaded binary packages.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/bin/xbps-reconfigure/xbps-reconfigure.8 b/bin/xbps-reconfigure/xbps-reconfigure.8
index 711bda75..216bff7e 100644
--- a/bin/xbps-reconfigure/xbps-reconfigure.8
+++ b/bin/xbps-reconfigure/xbps-reconfigure.8
@@ -1,4 +1,4 @@
-.Dd November 5, 2014
+.Dd December 9, 2014
 .Dt XBPS-RECONFIGURE 8
 .Sh NAME
 .Nm xbps-reconfigure
@@ -64,6 +64,7 @@ Default package database (0.38 format). Keeps track of installed packages and pr
 Default cache directory to store downloaded binary packages.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/bin/xbps-remove/xbps-remove.8 b/bin/xbps-remove/xbps-remove.8
index c75c9382..d153c639 100644
--- a/bin/xbps-remove/xbps-remove.8
+++ b/bin/xbps-remove/xbps-remove.8
@@ -1,4 +1,4 @@
-.Dd November 5, 2014
+.Dd December 9, 2014
 .Dt XBPS-REMOVE 8
 .Sh NAME
 .Nm xbps-remove
@@ -106,6 +106,7 @@ Default package database (0.38 format). Keeps track of installed packages and pr
 Default cache directory to store downloaded binary packages.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/bin/xbps-rindex/xbps-rindex.8 b/bin/xbps-rindex/xbps-rindex.8
index 6476f971..cff8b7f1 100644
--- a/bin/xbps-rindex/xbps-rindex.8
+++ b/bin/xbps-rindex/xbps-rindex.8
@@ -1,4 +1,4 @@
-.Dd December 6, 2014
+.Dd December 9, 2014
 .Dt XBPS-RINDEX 8
 .Sh NAME
 .Nm xbps-rindex
@@ -77,6 +77,7 @@ If this is set, it will use this passphrase for the RSA private key when signing
 a repository. Otherwise it will ask you to enter the passphrase on the terminal.
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/bin/xbps-uchroot/xbps-uchroot.8 b/bin/xbps-uchroot/xbps-uchroot.8
index fa9625d2..9dc6b883 100644
--- a/bin/xbps-uchroot/xbps-uchroot.8
+++ b/bin/xbps-uchroot/xbps-uchroot.8
@@ -1,4 +1,4 @@
-.Dd September 30, 2014
+.Dd December 9, 2014
 .Dt XBPS-UCHROOT 8
 .Sh NAME
 .Nm xbps-uchroot
@@ -56,6 +56,7 @@ other Operating Systems. The following kernel options must be enabled:
 .It Sy CONFIG_PID_NS
 .El
 .Sh SEE ALSO
+.Xr xbps.d 5 ,
 .Xr xbps-checkvers 8 ,
 .Xr xbps-create 8 ,
 .Xr xbps-dgraph 8 ,
diff --git a/data/Makefile b/data/Makefile
index 064316e6..43a53b27 100644
--- a/data/Makefile
+++ b/data/Makefile
@@ -11,6 +11,8 @@ all:
 
 .PHONY: install
 install:
+	install -d $(DESTDIR)$(SHAREDIR)/man/man5
+	install -m644 xbps.d.5 $(DESTDIR)$(SHAREDIR)/man/man5
 	install -d $(DESTDIR)$(PKGCONFIGDIR)
 	install -m644 $(PCFILE) $(DESTDIR)$(PKGCONFIGDIR)
 	install -d $(DESTDIR)/$(DBDIR)/keys
diff --git a/data/xbps.d.5 b/data/xbps.d.5
new file mode 100644
index 00000000..a8ebc112
--- /dev/null
+++ b/data/xbps.d.5
@@ -0,0 +1,141 @@
+.Dd December 9, 2014
+.Dt XBPS-D 5
+.Sh NAME
+.Nm xbps.d
+.Nd XBPS configuration directory
+.Sh SYNOPSYS
+.Bl -item -compact
+.It
+/etc/xbps.d/*.conf
+.It
+/usr/share/xbps.d/*.conf
+.El
+.Sh DESCRIPTION
+The
+.Nm
+configuration directory sets properties for the XBPS package manager.
+The
+.Sy configuration
+directory, by default set to
+.Sy /etc/xbps.d
+overrides settings from files available in the
+.Sy system configuration
+directory, by default set to
+.Sy /usr/share/xbps.d .
+Only files with the
+.Em .conf
+extension will be processed in alphabetical order.
+.Pp
+The configuration files can set multiple
+.Em keywords
+that are pairs of keys and values, such as
+.Sy `key=value` .
+No whitespace between the
+.Em key
+and its
+.Em value
+is allowed, nor trailing whitespaces after its value.
+.Sh KEYWORDS
+.Bl -tag -width -x
+.It Sy architecture=string
+Overrides the native machine architecture, as reported by
+.Xr uname 2 .
+.It Sy bestmaching=true|false
+When this keyword is enabled, a package with the greatest version available in
+all registered repositories will be choosen.
+This will be applied to dependencies as well.
+.It Sy cachedir=path
+Sets the default cache directory to store downloaded binary packages from
+remote repositories, as well as its signatures.
+If path starts with '\/' it's an absolute path, otherwise it will be relative to
+.Ar rootdir .
+.It Sy include=path/file.conf
+Imports settings from the specified configuration file.
+.Em NOTE
+only one level of nesting is allowed.
+.It Sy preserve=path
+If set ignores modifications to the specified files, while unpacking packages.
+Absolute path to a file and file globbing are supported, example:
+.Pp
+.Bl -tag -compact -width preserve=/etc/foo/*.conf
+.It Sy preserve=/usr/bin/foo
+.It Sy preserve=/etc/foo/*.conf
+.El
+.It Sy repository=url
+Declares a package repository. The
+.Ar url
+argument accepts local and remote repositories.
+A complete url or absolute path to the directory that stores the
+.Em <arch>-repodata
+archive is expected, example:
+.Bl -tag -compact -width repository=http://repo.voidlinux.eu/current
+.It Sy repository=http://repo.voidlinux.eu/current
+.It Sy repository=/hostdir/binpkgs
+.El
+.It Sy rootdir=path
+Sets the default root directory.
+.It Sy syslog=true|false
+Enables or disables syslog logging. Enabled by default.
+.It Sy virtualpkg=vpkgver:pkgname
+Declares a virtual package. A virtual package declaration is composed by two
+components delimited by a colon, i.e:
+.Pp
+.Bl -tag -compact -width virtualpkg=cron-daemon-1.0_1:dcron
+.It Sy virtualpkg=cron-daemon-1.0_1:dcron
+Any request to the
+.Ar cron-daemon
+virtual package will be resolved to the
+.Ar dcron
+real package.
+.El
+.Pp
+The first component expects a
+.Em virtual package name and its version component .
+The second component expects a
+.Em package name .
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width XBPS_TARGET_ARCH
+.It Sy XBPS_ARCH
+Overrides
+.Xr uname 2
+machine result with this value. Useful to install packages with a fake
+architecture.
+.It Sy XBPS_TARGET_ARCH
+Sets the target architecture to this value. This variable differs from
+.Sy XBPS_ARCH
+in that it allows you to install packages partially, because
+configuration phase is skipped (the target binaries might not be compatible with
+the native architecture).
+.El
+.Sh FILES
+.Bl -tag -width /var/db/xbps/.<pkgname>-files.plist
+.It Ar /etc/xbps.d
+Default configuration directory.
+.It Ar /usr/share/xbps.d
+Default system configuration directory.
+.It Ar /var/db/xbps/.<pkgname>-files.plist
+Package files metadata.
+.It Ar /var/db/xbps/pkgdb-0.38.plist
+Default package database (0.38 format). Keeps track of installed packages and properties.
+.It Ar /var/cache/xbps
+Default cache directory to store downloaded binary packages.
+.El
+.Sh SEE ALSO
+.Xr xbps-checkvers 8 ,
+.Xr xbps-create 8 ,
+.Xr xbps-dgraph 8 ,
+.Xr xbps-install 8 ,
+.Xr xbps-pkgdb 8 ,
+.Xr xbps-query 8 ,
+.Xr xbps-reconfigure 8 ,
+.Xr xbps-remove 8 ,
+.Xr xbps-rindex 8 ,
+.Xr xbps-uchroot 8
+.Sh AUTHORS
+.An Juan Romero Pardines <xtraeme@gmail.com>
+.Sh BUGS
+Probably, but I try to make this not happen. Use it under your own
+responsability and enjoy your life.
+.Pp
+Report bugs in https://github.com/voidlinux/xbps/issues