.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "KAFS 7"
.TH KAFS 7 "2023-02-05" "0.5-4" "kafs-client"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
kafs \- In\-kernel AFS filesystem
.SH ""
.IX Header ""
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`kafs\*(C'\fR is a network filesystem driver in the Linux kernel that is
able to access \s-1AFS\s0 cells and the servers contained therein to locate
the logical volumes that comprise the cell and the files contained in
each volume.
.PP
It supports transport over IPv4 \s-1UDP\s0 and IPv6 \s-1UDP\s0 and security based on
Kerberos.  The authentication token is used to define the user for the
purpose of providing access control as well as providing
communications security.
.PP
The filesystem is of type \*(L"afs\*(R" and the mount command can be used to
mount afs volumes manually using the \*(L"\-t\*(R" flag on \fBmount\fR(8).
.SH "SETTING UP"
.IX Header "SETTING UP"
The \f(CW\*(C`kafs\-client\*(C'\fR package should be installed to so that systemd is
configured to include a mount of \s-1AFS\s0 dynamic root on /afs.  Note that
mounting /afs is not enabled by default, so if it is needed, then
\&\f(CW\*(C`systemd\*(C'\fR should be told to enable it.  This can be done with the
following step:
.PP
.Vb 1
\&      systemctl enable afs.mount
.Ve
.PP
This will mount a special directory on \f(CW\*(C`/afs\*(C'\fR which will be populated
by an automount directory for each cell listed in the configuration.
Doing a pathwalk into one of these directories will result in the
\&\f(CW\*(C`afs.cell\*(C'\fR volume from the cell being mounted onto that directory.
.PP
Local configuration should be placed in a file in the
/etc/kafs/client.d/ directory.  This will be included from
/etc/client.conf file.
.PP
Typically in the local configuration, the local cell name would be
specified and backup details of its Volume Location server addresses
would be given.
.PP
Also any overrides for the \f(CW@sys\fR filename substitution would be
specified.  See \fBkafs\-client.conf\fR(5).
.SH "OPERATION"
.IX Header "OPERATION"
Once the kafs-client is set up (and if there's no local cell, this is
practically zero-conf, provided the cells to be accessed are properly
set up with \s-1AFSDB\s0 or \s-1SRV\s0 records in the \s-1DNS\s0), the /afs directory can
be accessed:
.PP
.Vb 1
\&      ls /afs/<cell>/location/within/cell
.Ve
.PP
For example:
.PP
.Vb 1
\&      ls /afs/rivendell.example.com/doc
.Ve
.PP
The user isn't limited to cells listed in /afs, but any cell can be
tried by just substituting the name of the cell into the above
formula.  It does require the target to have DNS-based configuration
provided.
.PP
Note that each logical volume gets a discrete superblock and links
between volumes turn into kernel mountpoints that, if stepped on,
cause the appropriate volume to be mounted over them.
.SH "SECURITY"
.IX Header "SECURITY"
kafs supports Kerberos-based authentication and communication
encryption through the use of Kerberos.  \f(CW\*(C`kinit\*(C'\fR program can
be use to authenticate with a Kerberos server:
.PP
.Vb 1
\&      kinit myname@RIVENDELL.EXAMPLE.COM
.Ve
.PP
and then the \f(CW\*(C`aklog\-kafs\*(C'\fR program to get a ticket for the kernel
filesystem to use:
.PP
.Vb 1
\&      aklog\-kafs rivendell.example.com
.Ve
.PP
This will be placed on the caller's session keyring and can be viewed
there with:
.PP
.Vb 1
\&      keyctl show
.Ve
.PP
Note that the default realm is assumed to be the same as the cell
name, but in all upper case.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBaklog-kafs\fR(1), \fBkafs\-client.conf\fR(5), \fBkeyctl\fR(1), \fBkinit\fR(1),
\&\fBrxrpc\fR(7), \fBsession-keyring\fR(7), \fBsystemctl\fR(1)
.SH "COPY RIGHT"
.IX Header "COPY RIGHT"
Copyright (C) 2019 Red Hat, Inc. All Rights Reserved.
.PP
Written by David Howells (dhowells@redhat.com)
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License as published by
the Free Software Foundation; either version 2 of the License, or (at
your option) any later version.