chiark / gitweb /
man: add sd_event_add_child(3)
[elogind.git] / man / file-hierarchy.xml
1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2014 Lennart Poettering
9
10   systemd is free software; you can redistribute it and/or modify it
11   under the terms of the GNU Lesser General Public License as published by
12   the Free Software Foundation; either version 2.1 of the License, or
13   (at your option) any later version.
14
15   systemd is distributed in the hope that it will be useful, but
16   WITHOUT ANY WARRANTY; without even the implied warranty of
17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18   Lesser General Public License for more details.
19
20   You should have received a copy of the GNU Lesser General Public License
21   along with systemd; If not, see <http://www.gnu.org/licenses/>.
22 -->
23
24 <refentry id="file-hierarchy">
25
26         <refentryinfo>
27                 <title>file-hierarchy</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>file-hierarchy</refentrytitle>
42                 <manvolnum>7</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>file-hierarchy</refname>
47                 <refpurpose>File system hierarchy overview</refpurpose>
48         </refnamediv>
49
50         <refsect1>
51                 <title>Description</title>
52
53                 <para>Operating systems using the
54                 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
55                 system and service manager are organized based on a
56                 file system hierarchy inspired by UNIX, more
57                 specifically the hierarchy described in the <ulink
58                 url="http://refspecs.linuxfoundation.org/FHS_2.3/fhs-2.3.html">File
59                 System Hierarchy</ulink> specification and
60                 <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>. This
61                 manual page describes a more minimal, modernized
62                 subset of these specifications that defines more
63                 strictly the suggestions and restrictions systemd
64                 makes on the file system hierarchy.</para>
65
66                 <para>Many of the paths described here are queriable
67                 with the
68                 <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>
69                 tool.</para>
70         </refsect1>
71
72         <refsect1>
73                 <title>General Structure</title>
74
75                 <variablelist>
76                         <varlistentry>
77                                 <term><filename>/</filename></term>
78                                 <listitem><para>The file system
79                                 root. Usually writable, but this is
80                                 not required. Possibly a temporary
81                                 file system (<literal>tmpfs</literal>). Not shared with
82                                 other hosts (unless read-only).
83                                 </para></listitem>
84                         </varlistentry>
85
86                         <varlistentry>
87                                 <term><filename>/boot</filename></term>
88                                 <listitem><para>The boot partition
89                                 used for bringing up the system. On
90                                 EFI systems this is possibly the EFI
91                                 System Partition, also see
92                                 <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>. This
93                                 directory is usually strictly local
94                                 to the host, and should be considered
95                                 read-only, except when a new kernel or
96                                 boot loader is installed. This
97                                 directory only exists on systems that
98                                 run on physical or emulated hardware
99                                 that requires boot
100                                 loaders.</para></listitem>
101                         </varlistentry>
102
103                         <varlistentry>
104                                 <term><filename>/etc</filename></term>
105                                 <listitem><para>System-specific
106                                 configuration. This directory may or
107                                 may not be read-only. Frequently, this
108                                 directory is pre-populated with
109                                 vendor-supplied configuration files,
110                                 but applications should not make
111                                 assumptions about this directory
112                                 being fully populated or populated at
113                                 all, and should fall back to defaults
114                                 if configuration is missing.</para></listitem>
115                         </varlistentry>
116
117                         <varlistentry>
118                                 <term><filename>/home</filename></term>
119                                 <listitem><para>The location for
120                                 normal user's home
121                                 directories. Possibly shared with
122                                 other systems, and never
123                                 read-only. This directory should only
124                                 be used for normal users, never for
125                                 system users. This directory and
126                                 possibly the directories contained
127                                 within it might only become available
128                                 or writable in late boot or even only
129                                 after user authentication. This directory
130                                 might be placed on limited-functionality
131                                 network file systems, hence
132                                 applications should not assume the
133                                 full set of file API is available on
134                                 this directory. Applications should
135                                 generally not reference this directory
136                                 directly, but via the per-user
137                                 <varname>$HOME</varname> environment
138                                 variable, or via the home directory
139                                 field of the user
140                                 database.</para></listitem>
141                         </varlistentry>
142
143                         <varlistentry>
144                                 <term><filename>/root</filename></term>
145                                 <listitem><para>The home directory of
146                                 the root user. The root user's home
147                                 directory is located outside of
148                                 <filename>/home</filename> in order to
149                                 make sure the root user may log in
150                                 even without <filename>/home</filename>
151                                 being available and
152                                 mounted.</para></listitem>
153                         </varlistentry>
154
155                         <varlistentry>
156                                 <term><filename>/srv</filename></term>
157                                 <listitem><para>The place to store
158                                 general server payload, managed by the
159                                 administrator. No restrictions are
160                                 made how this directory is organized
161                                 internally. Generally writable, and
162                                 possibly shared among systems. This
163                                 directory might become available or
164                                 writable only very late during
165                                 boot.</para></listitem>
166                         </varlistentry>
167
168                         <varlistentry>
169                                 <term><filename>/tmp</filename></term>
170                                 <listitem><para>The place for small
171                                 temporary files. This directory is
172                                 usually mounted as
173                                 a <literal>tmpfs</literal> instance, and
174                                 should hence not be used for larger
175                                 files. (Use
176                                 <filename>/var/tmp</filename> for
177                                 larger files.) Since the directory is
178                                 accessible to other users of the
179                                 system it is essential that this
180                                 directory is only written to with the
181                                 <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
182                                 <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
183                                 and related calls. This directory is
184                                 usually flushed at boot-up. Also,
185                                 files that are not accessed within a
186                                 certain time are usually automatically
187                                 deleted. If applications find the
188                                 environment variable
189                                 <varname>$TMPDIR</varname> set they
190                                 should prefer using the directory
191                                 specified in it over directly
192                                 referencing
193                                 <filename>/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>
194                                 and
195                                 <ulink url="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap08.html#tag_08_03">IEEE Std 1003.1</ulink> for details).</para></listitem>
196                         </varlistentry>
197
198                 </variablelist>
199         </refsect1>
200
201         <refsect1>
202                 <title>Runtime Data</title>
203
204                 <variablelist>
205                         <varlistentry>
206                                 <term><filename>/run</filename></term>
207                                 <listitem><para>A
208                                 <literal>tmpfs</literal> file system
209                                 for system packages to place runtime
210                                 data in. This directory is flushed on
211                                 boot, and generally writable for
212                                 privileged programs
213                                 only. Always writable.</para></listitem>
214                         </varlistentry>
215
216                         <varlistentry>
217                                 <term><filename>/run/log</filename></term>
218                                 <listitem><para>Runtime system
219                                 logs. System components may place
220                                 private logs in this directory. Always
221                                 writable, even when
222                                 <filename>/var/log</filename> might
223                                 not be accessible
224                                 yet.</para></listitem>
225                         </varlistentry>
226
227                         <varlistentry>
228                                 <term><filename>/run/user</filename></term>
229                                 <listitem><para>Contains per-user
230                                 runtime directories, each usually
231                                 individually mounted
232                                 <literal>tmpfs</literal>
233                                 instances. Always writable, flushed at
234                                 each reboot and when the user logs
235                                 out. User code should not reference
236                                 this directory directly, but via the
237                                 <varname>$XDG_RUNTIME_DIR</varname>
238                                 environment variable, as documented in
239                                 the <ulink
240                                 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
241                                 Base Directory
242                                 Specification</ulink>.</para></listitem>
243                         </varlistentry>
244                 </variablelist>
245         </refsect1>
246
247         <refsect1>
248                 <title>Vendor-supplied Operating System Resources</title>
249
250                 <variablelist>
251
252                         <varlistentry>
253                                 <term><filename>/usr</filename></term>
254                                 <listitem><para>Vendor-supplied
255                                 operating system resources. Usually
256                                 read-only, but this is not
257                                 required. Possibly shared between
258                                 multiple hosts. This directory should
259                                 not be modified by the administrator,
260                                 except when installing or removing
261                                 vendor-supplied
262                                 packages.</para></listitem>
263                         </varlistentry>
264
265                         <varlistentry>
266                                 <term><filename>/usr/bin</filename></term>
267                                 <listitem><para>Binaries and
268                                 executables for user commands, that
269                                 shall appear in the
270                                 <varname>$PATH</varname> search
271                                 path. It is recommended not to place
272                                 binaries in this directory that are
273                                 not useful for invocation from a shell
274                                 (such as daemon binaries); these
275                                 should be placed in a subdirectory of
276                                 <filename>/usr/lib</filename>
277                                 instead.</para></listitem>
278                         </varlistentry>
279
280                         <varlistentry>
281                                 <term><filename>/usr/include</filename></term>
282                                 <listitem><para>C and C++ API header
283                                 files of system
284                                 libraries.</para></listitem>
285                         </varlistentry>
286
287                         <varlistentry>
288                                 <term><filename>/usr/lib</filename></term>
289                                 <listitem><para>Static, private vendor
290                                 data that is compatible with all
291                                 architectures (though not necessarily
292                                 architecture-independent). Note that
293                                 this includes internal executables or
294                                 other binaries that are not regularly
295                                 invoked from a shell. Such binaries
296                                 may be for any architecture supported
297                                 by the system. Do not place public
298                                 libraries in this directory, use
299                                 <varname>$libdir</varname> (see
300                                 below), instead.</para></listitem>
301                         </varlistentry>
302
303                         <varlistentry>
304                                 <term><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></term>
305                                 <listitem><para>Location for placing
306                                 dynamic libraries, also called <varname>$libdir</varname>.
307                                 The architecture identifier to use is defined on <ulink
308                                 url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink>
309                                 list. Legacy locations of <varname>$libdir</varname> are
310                                 <filename>/usr/lib</filename>,
311                                 <filename>/usr/lib64</filename>.
312                                 This directory should not
313                                 be used for package-specific data,
314                                 unless this data is
315                                 architecture-dependent, too. To query
316                                 <varname>$libdir</varname> for the
317                                 primary architecture of the system,
318                                 invoke:
319                                 <programlisting># pkg-config --variable=libdir systemd</programlisting> or
320                                 <programlisting># systemd-path system-library-arch</programlisting>
321                                 </para></listitem>
322
323                         </varlistentry>
324
325                         <varlistentry>
326                                 <term><filename>/usr/share</filename></term>
327                                 <listitem><para>Resources shared
328                                 between multiple packages, such as
329                                 documentation, man pages, time zone
330                                 information, fonts and other
331                                 resources. Usually, the precise
332                                 location and format of files stored
333                                 below this directory is subject to
334                                 specifications that ensure
335                                 interoperability.</para></listitem>
336                         </varlistentry>
337
338                         <varlistentry>
339                                 <term><filename>/usr/share/doc</filename></term>
340                                 <listitem><para>Documentation for the
341                                 operating system or system
342                                 packages.</para></listitem>
343                         </varlistentry>
344
345                         <varlistentry>
346                                 <term><filename>/usr/share/factory/etc</filename></term>
347                                 <listitem><para>Repository for
348                                 vendor-supplied default configuration
349                                 files. This directory should be
350                                 populated with pristine vendor versions
351                                 of all configuration files that may be
352                                 placed in
353                                 <filename>/etc</filename>. This is
354                                 useful to compare the local
355                                 configuration of a system with vendor
356                                 defaults and to populate the local
357                                 configuration with
358                                 defaults.</para></listitem>
359                         </varlistentry>
360
361                         <varlistentry>
362                                 <term><filename>/usr/share/factory/var</filename></term>
363
364                                 <listitem><para>Similar to
365                                 <filename>/usr/share/factory/etc</filename>
366                                 but for vendor versions of files in
367                                 the variable, persistent data
368                                 directory
369                                 <filename>/var</filename>.</para></listitem>
370
371                         </varlistentry>
372                 </variablelist>
373         </refsect1>
374
375         <refsect1>
376                 <title>Persistent Variable System Data</title>
377
378                 <variablelist>
379                         <varlistentry>
380                                 <term><filename>/var</filename></term>
381                                 <listitem><para>Persistent, variable
382                                 system data. Must be writable. This
383                                 directory might be pre-populated with
384                                 vendor-supplied data, but applications
385                                 should be able to reconstruct
386                                 necessary files and directories in
387                                 this subhierarchy should they be
388                                 missing, as the system might start up
389                                 without this directory being
390                                 populated. Persistency is recommended,
391                                 but optional, to support ephemeral
392                                 systems. This directory might become
393                                 available or writable only very late
394                                 during boot. Components that are
395                                 required to operate during early boot
396                                 hence shall not unconditionally rely
397                                 on this directory.</para></listitem>
398                         </varlistentry>
399
400                         <varlistentry>
401                                 <term><filename>/var/cache</filename></term>
402                                 <listitem><para>Persistent system
403                                 cache data. System components may
404                                 place non-essential data in this
405                                 directory. Flushing this directory
406                                 should have no effect on operation of
407                                 programs, except for increased
408                                 runtimes necessary to rebuild these
409                                 caches.</para></listitem>
410                         </varlistentry>
411
412                         <varlistentry>
413                                 <term><filename>/var/lib</filename></term>
414                                 <listitem><para>Persistent system
415                                 data. System components may
416                                 place private data in this
417                                 directory.</para></listitem>
418                         </varlistentry>
419
420                         <varlistentry>
421                                 <term><filename>/var/log</filename></term>
422                                 <listitem><para>Persistent system
423                                 logs. System components may place
424                                 private logs in this directory, though
425                                 it is recommended to do most logging
426                                 via the
427                                 <citerefentry project='man-pages'><refentrytitle>syslog</refentrytitle><manvolnum>3</manvolnum></citerefentry>
428                                 and
429                                 <citerefentry><refentrytitle>sd_journal_print</refentrytitle><manvolnum>3</manvolnum></citerefentry>
430                                 calls.</para></listitem>
431                         </varlistentry>
432
433                         <varlistentry>
434                                 <term><filename>/var/spool</filename></term>
435                                 <listitem><para>Persistent system
436                                 spool data, such as printer or mail
437                                 queues.</para></listitem>
438                         </varlistentry>
439
440                         <varlistentry>
441                                 <term><filename>/var/tmp</filename></term>
442                                 <listitem><para>The place for larger
443                                 and persistent temporary files. In
444                                 contrast to <filename>/tmp</filename>
445                                 this directory is usually mounted from
446                                 a persistent physical file system and
447                                 can thus accept larger files. (Use
448                                 <filename>/tmp</filename> for smaller
449                                 files.) This directory is generally
450                                 not flushed at boot-up, but time-based
451                                 cleanup of files that have not been
452                                 accessed for a certain time is
453                                 applied. The same security
454                                 restrictions as with
455                                 <filename>/tmp</filename> apply, and
456                                 hence only
457                                 <citerefentry project='man-pages'><refentrytitle>mkstemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
458                                 <citerefentry project='man-pages'><refentrytitle>mkdtemp</refentrytitle><manvolnum>3</manvolnum></citerefentry>
459                                 or similar calls should be used to
460                                 make use of this directory. If
461                                 applications find the environment
462                                 variable <varname>$TMPDIR</varname>
463                                 set they should prefer using the
464                                 directory specified in it over
465                                 directly referencing
466                                 <filename>/var/tmp</filename> (see <citerefentry project='man-pages'><refentrytitle>environ</refentrytitle><manvolnum>7</manvolnum></citerefentry>
467                                 for details).
468                                 </para></listitem>
469                         </varlistentry>
470
471                 </variablelist>
472         </refsect1>
473
474         <refsect1>
475                 <title>Virtual Kernel and API File Systems</title>
476
477                 <variablelist>
478                         <varlistentry>
479                                 <term><filename>/dev</filename></term>
480                                 <listitem><para>The root directory for
481                                 device nodes. Usually this directory
482                                 is mounted as a
483                                 <literal>devtmpfs</literal> instance,
484                                 but might be of a different type in
485                                 sandboxed/containerized setups. This
486                                 directory is managed jointly by the
487                                 kernel and
488                                 <citerefentry><refentrytitle>systemd-udevd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
489                                 and should not be written to by other
490                                 components. A number of special
491                                 purpose virtual file systems might be
492                                 mounted below this
493                                 directory.</para></listitem>
494                         </varlistentry>
495
496                         <varlistentry>
497                                 <term><filename>/dev/shm</filename></term>
498                                 <listitem><para>Place for POSIX shared
499                                 memory segments, as created via
500                                 <citerefentry><refentrytitle>shm_open</refentrytitle><manvolnum>3</manvolnum></citerefentry>. This
501                                 directory is flushed on boot, and is a
502                                 <literal>tmpfs</literal> file
503                                 system. Since all users have write
504                                 access to this directory, special care
505                                 should be taken to avoid name clashes
506                                 and vulnerabilities. For normal users,
507                                 shared memory segments in this
508                                 directory are usually deleted when the
509                                 user logs out. Usually it is a better
510                                 idea to use memory mapped files in
511                                 <filename>/run</filename> (for system
512                                 programs) or
513                                 <varname>$XDG_RUNTIME_DIR</varname>
514                                 (for user programs) instead of POSIX
515                                 shared memory segments, since those
516                                 directories are not world-writable and
517                                 hence not vulnerable to
518                                 security-sensitive name
519                                 clashes.</para></listitem>
520                         </varlistentry>
521
522                         <varlistentry>
523                                 <term><filename>/proc</filename></term>
524                                 <listitem><para>A virtual kernel file
525                                 system exposing the process list and
526                                 other functionality. This file system
527                                 is mostly an API to interface with the
528                                 kernel and not a place where normal
529                                 files may be stored. For details, see
530                                 <citerefentry project='man-pages'><refentrytitle>proc</refentrytitle><manvolnum>5</manvolnum></citerefentry>. A
531                                 number of special purpose virtual file
532                                 systems might be mounted below this
533                                 directory.</para></listitem>
534                         </varlistentry>
535
536                         <varlistentry>
537                                 <term><filename>/proc/sys</filename></term>
538                                 <listitem><para>A hierarchy below
539                                 <filename>/proc</filename> that
540                                 exposes a number of kernel
541                                 tunables. The primary way to configure
542                                 the settings in this API file tree is
543                                 via
544                                 <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
545                                 files. In sandboxed/containerized
546                                 setups this directory is generally
547                                 mounted read-only.</para></listitem>
548                         </varlistentry>
549
550                         <varlistentry>
551                                 <term><filename>/sys</filename></term>
552                                 <listitem><para>A virtual kernel file
553                                 system exposing discovered devices and
554                                 other functionality. This file system
555                                 is mostly an API to interface with the
556                                 kernel and not a place where normal
557                                 files may be stored. In
558                                 sandboxed/containerized setups this
559                                 directory is generally mounted
560                                 read-only. A number of special purpose
561                                 virtual file systems might be mounted
562                                 below this
563                                 directory.</para></listitem>
564                         </varlistentry>
565
566
567                 </variablelist>
568         </refsect1>
569
570         <refsect1>
571                 <title>Compatibility Symlinks</title>
572
573                 <variablelist>
574                         <varlistentry>
575                                 <term><filename>/bin</filename></term>
576                                 <term><filename>/sbin</filename></term>
577                                 <term><filename>/usr/sbin</filename></term>
578
579                                 <listitem><para>These compatibility
580                                 symlinks point to
581                                 <filename>/usr/bin</filename>,
582                                 ensuring that scripts and binaries
583                                 referencing these legacy paths
584                                 correctly find their binaries.</para></listitem>
585                         </varlistentry>
586
587                         <varlistentry>
588                                 <term><filename>/lib</filename></term>
589
590                                 <listitem><para>This compatibility
591                                 symlink points to
592                                 <filename>/usr/lib</filename>,
593                                 ensuring that programs referencing
594                                 this legacy path correctly find
595                                 their resources.</para></listitem>
596                         </varlistentry>
597
598                         <varlistentry>
599                                 <term><filename>/lib64</filename></term>
600
601                                 <listitem><para>On some architecture
602                                 ABIs this compatibility symlink points
603                                 to <varname>$libdir</varname>,
604                                 ensuring that binaries referencing
605                                 this legacy path correctly find their
606                                 dynamic loader. This symlink only
607                                 exists on architectures whose ABI
608                                 places the dynamic loader in this
609                                 path.</para></listitem>
610                         </varlistentry>
611
612                         <varlistentry>
613                                 <term><filename>/var/run</filename></term>
614
615                                 <listitem><para>This compatibility
616                                 symlink points to
617                                 <filename>/run</filename>, ensuring
618                                 that programs referencing this legacy
619                                 path correctly find their runtime
620                                 data.</para></listitem>
621                         </varlistentry>
622
623                 </variablelist>
624         </refsect1>
625
626         <refsect1>
627                 <title>Home Directory</title>
628
629                 <para>User applications may want to place files and
630                 directories in the user's home directory. They should
631                 follow the following basic structure. Note that some
632                 of these directories are also standardized (though
633                 more weakly) by the <ulink
634                 url="http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html">XDG
635                 Base Directory Specification</ulink>. Additional
636                 locations for high-level user resources are defined by
637                 <ulink
638                 url="http://www.freedesktop.org/wiki/Software/xdg-user-dirs/">xdg-user-dirs</ulink>.</para>
639
640                 <variablelist>
641                         <varlistentry>
642                                 <term><filename>~/.cache</filename></term>
643
644                                 <listitem><para>Persistent user cache
645                                 data. User programs may place
646                                 non-essential data in this
647                                 directory. Flushing this directory
648                                 should have no effect on operation of
649                                 programs, except for increased
650                                 runtimes necessary to rebuild these
651                                 caches. If an application finds
652                                 <varname>$XDG_CACHE_HOME</varname> set
653                                 is should use the directory specified
654                                 in it instead of this
655                                 directory.</para></listitem>
656                         </varlistentry>
657
658                         <varlistentry>
659                                 <term><filename>~/.config</filename></term>
660
661                                 <listitem><para>Application
662                                 configuration and state. When a new
663                                 user is created this directory will be
664                                 empty or not exist at
665                                 all. Applications should fall back to
666                                 defaults should their configuration or
667                                 state in this directory be missing. If
668                                 an application finds
669                                 <varname>$XDG_CONFIG_HOME</varname> set
670                                 is should use the directory specified
671                                 in it instead of this
672                                 directory.</para></listitem>
673                         </varlistentry>
674
675                         <varlistentry>
676                                 <term><filename>~/.local/bin</filename></term>
677
678                                 <listitem><para>Executables that shall
679                                 appear in the user's
680                                 <varname>$PATH</varname> search
681                                 path. It is recommended not to place
682                                 executables in this directory that are
683                                 not useful for invocation from a
684                                 shell; these should be placed in a
685                                 subdirectory of
686                                 <filename>~/.local/lib</filename>
687                                 instead. Care should be taken when
688                                 placing architecture-dependent
689                                 binaries in this place which might be
690                                 problematic if the home directory is
691                                 shared between multiple hosts with
692                                 different
693                                 architectures.</para></listitem>
694                         </varlistentry>
695
696                         <varlistentry>
697                                 <term><filename>~/.local/lib</filename></term>
698
699                                 <listitem><para>Static, private vendor
700                                 data that is compatible with all
701                                 architectures.</para></listitem>
702                         </varlistentry>
703
704                         <varlistentry>
705                                 <term><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></term>
706
707                                 <listitem><para>Location for placing
708                                 public dynamic libraries. The architecture
709                                 identifier to use, is defined on <ulink
710                                 url="https://wiki.debian.org/Multiarch/Tuples">Multiarch Architecture Specifiers (Tuples)</ulink>
711                                 list.</para></listitem>
712                         </varlistentry>
713
714                         <varlistentry>
715                                 <term><filename>~/.local/share</filename></term>
716
717                                 <listitem><para>Resources shared
718                                 between multiple packages, such as
719                                 fonts or artwork. Usually, the precise
720                                 location and format of files stored
721                                 below this directory is subject to
722                                 specifications that ensure
723                                 interoperability. If
724                                 an application finds
725                                 <varname>$XDG_DATA_HOME</varname> set
726                                 is should use the directory specified
727                                 in it instead of this
728                                 directory.</para></listitem>
729                         </varlistentry>
730
731                 </variablelist>
732         </refsect1>
733
734
735         <refsect1>
736                 <title>Unprivileged Write Access</title>
737
738                 <para>Unprivileged processes generally lack
739                 write access to most of the hierarchy.</para>
740
741                 <para>The exceptions for normal users are
742                 <filename>/tmp</filename>,
743                 <filename>/var/tmp</filename>,
744                 <filename>/dev/shm</filename>, as well as the home
745                 directory <varname>$HOME</varname> (usually found
746                 below <filename>/home</filename>) and the runtime
747                 directory <varname>$XDG_RUNTIME_DIR</varname> (found
748                 below <filename>/run/user</filename>) of the
749                 user, which are all writable.</para>
750
751                 <para>For unprivileged system processes only
752                 <filename>/tmp</filename>,
753                 <filename>/var/tmp</filename> and
754                 <filename>/dev/shm</filename> are writable. If an
755                 unprivileged system process needs a private, writable
756                 directory in <filename>/var</filename> or
757                 <filename>/run</filename>, it is recommended to either
758                 create it before dropping privileges in the daemon
759                 code, to create it via
760                 <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>
761                 fragments during boot, or via the
762                 <varname>RuntimeDirectory=</varname> directive of
763                 service units (see
764                 <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
765                 for details).</para>
766         </refsect1>
767
768         <refsect1>
769                 <title>Node Types</title>
770
771                 <para>Unix file systems support different types of file
772                 nodes, including regular files, directories, symlinks,
773                 character and block device nodes, sockets and FIFOs.</para>
774
775                 <para>It is strongly recommended that
776                 <filename>/dev</filename> is the only location below
777                 which device nodes shall be placed. Similar,
778                 <filename>/run</filename> shall be the only location
779                 to place sockets and FIFOs. Regular files,
780                 directories and symlinks may be used in all
781                 directories.</para>
782         </refsect1>
783
784         <refsect1>
785                 <title>System Packages</title>
786
787                 <para>Developers of system packages should follow
788                 strict rules when placing their own files in the file
789                 system. The following table lists recommended
790                 locations for specific types of files supplied by the
791                 vendor.</para>
792
793                 <table>
794                   <title>System Package Vendor Files Locations</title>
795                   <tgroup cols='2' align='left' colsep='1' rowsep='1'>
796                     <colspec colname="directory" />
797                     <colspec colname="purpose" />
798                     <thead>
799                       <row>
800                         <entry>Directory</entry>
801                         <entry>Purpose</entry>
802                       </row>
803                     </thead>
804                     <tbody>
805                       <row>
806                         <entry><filename>/usr/bin</filename></entry>
807                         <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path, compiled for any of the supported architectures compatible with the operating system. It is not recommended to place internal binaries or binaries that are not commonly invoked from the shell in this directory, such as daemon binaries. As this directory is shared with most other packages of the system special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
808                       </row>
809                       <row>
810                         <entry><filename>/usr/lib/<replaceable>arch-id</replaceable></filename></entry>
811                         <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
812                       </row>
813                       <row>
814                         <entry><filename>/usr/lib/<replaceable>package</replaceable></filename></entry>
815                         <entry>Private, static vendor resources of the package, including private binaries and libraries, or any other kind of read-only vendor data.</entry>
816                       </row>
817                       <row>
818                         <entry><filename>/usr/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry>
819                         <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures. Note that this generally does not include private executables since binaries of a specific architecture may be freely invoked from any other supported system architecture.</entry>
820                       </row>
821                       <row>
822                         <entry><filename>/usr/include/<replaceable>package</replaceable></filename></entry>
823                         <entry>Public C/C++ APIs of public shared libraries of the package.</entry>
824                       </row>
825                     </tbody>
826                   </tgroup>
827                 </table>
828
829                 <para>Additional static vendor files may be installed
830                 in the <filename>/usr/share</filename> hierarchy, to
831                 the locations defined by the various relevant
832                 specifications.</para>
833
834                 <para>During runtime and for local configuration and
835                 state additional directories are defined:</para>
836
837                 <table>
838                   <title>System Package Variable Files Locations</title>
839                   <tgroup cols='2' align='left' colsep='1' rowsep='1'>
840                     <colspec colname="directory" />
841                     <colspec colname="purpose" />
842                     <thead>
843                       <row>
844                         <entry>Directory</entry>
845                         <entry>Purpose</entry>
846                       </row>
847                     </thead>
848                     <tbody>
849                       <row>
850                         <entry><filename>/etc/<replaceable>package</replaceable></filename></entry>
851                         <entry>System-specific configuration for the package. It is recommended to default to safe fallbacks if this configuration is missing, if this is possible. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to copy or symlink the necessary files and directories from <filename>/usr/share/factory</filename> during boot, via the <literal>L</literal> or <literal>C</literal> directives.</entry>
852                       </row>
853                       <row>
854                         <entry><filename>/run/<replaceable>package</replaceable></filename></entry>
855                         <entry>Runtime data for the package. Packages must be able to create the necessary subdirectories in this tree on their own, since the directory is flushed automatically on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot. Alternatively, the <varname>RuntimeDirectory=</varname> directive of service units may be used (see <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry> for details.)</entry>
856                       </row>
857                       <row>
858                         <entry><filename>/run/log/<replaceable>package</replaceable></filename></entry>
859                         <entry>Runtime log data for the package. As above, the package needs to make sure to create this directory if necessary, as it will be flushed on every boot.</entry>
860                       </row>
861                       <row>
862                         <entry><filename>/var/cache/<replaceable>package</replaceable></filename></entry>
863                         <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry>
864                       </row>
865                       <row>
866                         <entry><filename>/var/lib/<replaceable>package</replaceable></filename></entry>
867                         <entry>Persistent private data of the package. This is the primary place to put persistent data that does not fall into the other categories listed. Packages should be able to create the necessary subdirectories in this tree on their own, since the directory might be missing on boot. Alternatively, a <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry> fragment may be used to create the necessary directories during boot.</entry>
868                       </row>
869                       <row>
870                         <entry><filename>/var/log/<replaceable>package</replaceable></filename></entry>
871                         <entry>Persistent log data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
872                       </row>
873                       <row>
874                         <entry><filename>/var/spool/<replaceable>package</replaceable></filename></entry>
875                         <entry>Persistent spool/queue data of the package. As above, the package should make sure to create this directory if necessary, as it might be missing.</entry>
876                       </row>
877                     </tbody>
878                   </tgroup>
879                 </table>
880         </refsect1>
881
882         <refsect1>
883                 <title>User Packages</title>
884
885                 <para>Programs running in user context should follow
886                 strict rules when placing their own files in the
887                 user's home directory. The following table lists
888                 recommended locations in the home directory for
889                 specific types of files supplied by the vendor if the
890                 application is installed in the home directory. (Note
891                 however, that user applications installed system-wide
892                 should follow the rules outlined above regarding
893                 placing vendor files.)</para>
894
895                 <table>
896                   <title>User Package Vendor File Locations</title>
897                   <tgroup cols='2' align='left' colsep='1' rowsep='1'>
898                     <colspec colname="directory" />
899                     <colspec colname="purpose" />
900                     <thead>
901                       <row>
902                         <entry>Directory</entry>
903                         <entry>Purpose</entry>
904                       </row>
905                     </thead>
906                     <tbody>
907                       <row>
908                         <entry><filename>~/.local/bin</filename></entry>
909                         <entry>Package executables that shall appear in the <varname>$PATH</varname> executable search path. It is not recommended to place internal executables or executables that are not commonly invoked from the shell in this directory, such as daemon executables. As this directory is shared with most other packages of the user special care should be taken to pick unique names for files placed here, that are unlikely to clash with other package's files.</entry>
910                       </row>
911                       <row>
912                         <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable></filename></entry>
913                         <entry>Public shared libraries of the package. As above, be careful with using too generic names, and pick unique names for your libraries to place here to avoid name clashes.</entry>
914                       </row>
915                       <row>
916                         <entry><filename>~/.local/lib/<replaceable>package</replaceable></filename></entry>
917                         <entry>Private, static vendor resources of the package, compatible with any architecture, or any other kind of read-only vendor data.</entry>
918                       </row>
919                       <row>
920                         <entry><filename>~/.local/lib/<replaceable>arch-id</replaceable>/<replaceable>package</replaceable></filename></entry>
921                         <entry>Private other vendor resources of the package that are architecture-specific and cannot be shared between architectures.</entry>
922                       </row>
923                     </tbody>
924                   </tgroup>
925                 </table>
926
927                 <para>Additional static vendor files may be installed
928                 in the <filename>~/.local/share</filename> hierarchy,
929                 to the locations defined by the various relevant
930                 specifications.</para>
931
932                 <para>During runtime and for local configuration and
933                 state additional directories are defined:</para>
934
935                 <table>
936                   <title>User Package Variable File Locations</title>
937                   <tgroup cols='2' align='left' colsep='1' rowsep='1'>
938                     <colspec colname="directory" />
939                     <colspec colname="purpose" />
940                     <thead>
941                       <row>
942                         <entry>Directory</entry>
943                         <entry>Purpose</entry>
944                       </row>
945                     </thead>
946                     <tbody>
947                       <row>
948                         <entry><filename>~/.config/<replaceable>package</replaceable></filename></entry>
949                         <entry>User-specific configuration and state for the package. It is required to default to safe fallbacks if this configuration is missing.</entry>
950                       </row>
951                       <row>
952                         <entry><filename><varname>$XDG_RUNTIME_DIR</varname>/<replaceable>package</replaceable></filename></entry>
953                         <entry>User runtime data for the package.</entry>
954                       </row>
955                       <row>
956                         <entry><filename>~/.cache/<replaceable>package</replaceable></filename></entry>
957                         <entry>Persistent cache data of the package. If this directory is flushed the application should work correctly on next invocation, though possibly slowed down due to the need to rebuild any local cache files. The application must be capable of recreating this directory should it be missing and necessary.</entry>
958                       </row>
959                     </tbody>
960                   </tgroup>
961                 </table>
962         </refsect1>
963
964         <refsect1>
965                 <title>See Also</title>
966                 <para>
967                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
968                         <citerefentry project='man-pages'><refentrytitle>hier</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
969                         <citerefentry><refentrytitle>systemd-path</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
970                         <citerefentry><refentrytitle>systemd-efi-boot-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
971                         <citerefentry><refentrytitle>sysctl.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
972                         <citerefentry><refentrytitle>tmpfiles.d</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
973                         <citerefentry project='die-net'><refentrytitle>pkg-config</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
974                         <citerefentry><refentrytitle>systemd.unit</refentrytitle><manvolnum>5</manvolnum></citerefentry>
975                 </para>
976         </refsect1>
977
978 </refentry>