summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/README4
-rw-r--r--doc/admin/admin_commands/kadmin_local.rst1
-rw-r--r--doc/admin/admin_commands/krb5kdc.rst4
-rw-r--r--doc/admin/conf_files/kadm5_acl.rst5
-rw-r--r--doc/admin/conf_files/kdc_conf.rst4
-rw-r--r--doc/admin/conf_files/krb5_conf.rst4
-rw-r--r--doc/admin/database.rst32
-rw-r--r--doc/admin/install_kdc.rst41
-rw-r--r--doc/admin/troubleshoot.rst8
-rw-r--r--doc/appdev/gssapi.rst12
-rw-r--r--doc/basic/date_format.rst2
-rw-r--r--doc/basic/stash_file_def.rst4
-rw-r--r--doc/plugindev/profile.rst4
-rw-r--r--doc/tools/func_document.tmpl3
-rw-r--r--doc/user/tkt_mgmt.rst4
-rw-r--r--doc/user/user_commands/ksu.rst8
16 files changed, 108 insertions, 32 deletions
diff --git a/doc/README b/doc/README
index 8bb1c47cc5..a49d11038f 100644
--- a/doc/README
+++ b/doc/README
@@ -67,3 +67,7 @@ We use the following conventions:
to indicate optional parameters). If immediately following one kind
of inline markup with another or putting inline markup next to
punctuation, you may need to use "\ " as a dummy separator.
+
+* For directives that take a content block (e.g., note, error, and
+ warning), leave a blank line before the content block (after any
+ arguments or options that may be present).
diff --git a/doc/admin/admin_commands/kadmin_local.rst b/doc/admin/admin_commands/kadmin_local.rst
index c15042b139..6fee6166f0 100644
--- a/doc/admin/admin_commands/kadmin_local.rst
+++ b/doc/admin/admin_commands/kadmin_local.rst
@@ -306,6 +306,7 @@ Options:
Associates a ticket policy to the Kerberos principal.
.. note::
+
- The **containerdn** and **linkdn** options cannot be
specified with the **dn** option.
- If the *dn* or *containerdn* options are not specified while
diff --git a/doc/admin/admin_commands/krb5kdc.rst b/doc/admin/admin_commands/krb5kdc.rst
index 62afca4ee6..f5b37bca38 100644
--- a/doc/admin/admin_commands/krb5kdc.rst
+++ b/doc/admin/admin_commands/krb5kdc.rst
@@ -72,7 +72,9 @@ will relay SIGHUP signals to the worker subprocesses, and will
terminate the worker subprocess if the it is itself terminated or if
any other worker process exits.
-.. note:: On operating systems which do not have *pktinfo* support,
+.. note::
+
+ On operating systems which do not have *pktinfo* support,
using worker processes will prevent the KDC from listening
for UDP packets on network interfaces created after the KDC
starts.
diff --git a/doc/admin/conf_files/kadm5_acl.rst b/doc/admin/conf_files/kadm5_acl.rst
index 4a8e0741e0..ffebe90bb7 100644
--- a/doc/admin/conf_files/kadm5_acl.rst
+++ b/doc/admin/conf_files/kadm5_acl.rst
@@ -25,7 +25,9 @@ ignored. Lines containing ACL entries have the format:
principal permissions [target_principal [restrictions] ]
-.. note:: Line order in the ACL file is important. The first matching entry
+.. note::
+
+ Line order in the ACL file is important. The first matching entry
will control access for an actor principal on a target principal.
*principal*
@@ -88,6 +90,7 @@ ignored. Lines containing ACL entries have the format:
which is allowed due to that ACL line.
.. warning::
+
If the kadmind ACL file is modified, the kadmind daemon needs to be
restarted for changes to take effect.
diff --git a/doc/admin/conf_files/kdc_conf.rst b/doc/admin/conf_files/kdc_conf.rst
index 4da8d936f2..7631431051 100644
--- a/doc/admin/conf_files/kdc_conf.rst
+++ b/doc/admin/conf_files/kdc_conf.rst
@@ -491,7 +491,9 @@ administrative server will be appended to the file
PKINIT options
--------------
-.. note:: The following are pkinit-specific options. These values may
+.. note::
+
+ The following are pkinit-specific options. These values may
be specified in [kdcdefaults] as global defaults, or within
a realm-specific subsection of [realms]. Also note that a
realm-specific value over-rides, does not add to, a generic
diff --git a/doc/admin/conf_files/krb5_conf.rst b/doc/admin/conf_files/krb5_conf.rst
index 5dbbfa49b4..6911f5c69a 100644
--- a/doc/admin/conf_files/krb5_conf.rst
+++ b/doc/admin/conf_files/krb5_conf.rst
@@ -724,7 +724,9 @@ built-in modules exist for these interfaces:
PKINIT options
--------------
-.. note:: The following are PKINIT-specific options. These values may
+.. note::
+
+ The following are PKINIT-specific options. These values may
be specified in [libdefaults] as global defaults, or within
a realm-specific subsection of [libdefaults], or may be
specified as realm-specific values in the [realms] section.
diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index e2acb94c4c..a110d21351 100644
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -179,7 +179,9 @@ To change a principal's password use the :ref:`kadmin(1)`
:start-after: _change_password:
:end-before: _change_password_end:
-.. note:: Password changes through kadmin are subject to the same
+.. note::
+
+ Password changes through kadmin are subject to the same
password policies as would apply to password changes through
:ref:`kpasswd(1)`.
@@ -217,7 +219,9 @@ To delete a policy, use the kadmin **delete_policy** command.
:start-after: _delete_policy:
:end-before: _delete_policy_end:
-.. note:: You must cancel the policy from *all* principals before
+.. note::
+
+ You must cancel the policy from *all* principals before
deleting it. The *delete_policy* command will fail if the policy
is in use by any principals.
@@ -270,7 +274,9 @@ Privileges
Administrative privileges for the Kerberos database are stored in the
file :ref:`kadm5.acl(5)`.
-.. note:: A common use of an admin instance is so you can grant
+.. note::
+
+ A common use of an admin instance is so you can grant
separate permissions (such as administrator access to the
Kerberos database) to a separate Kerberos principal. For
example, the user ``joeadmin`` might have a principal for
@@ -373,7 +379,9 @@ To load a single principal, either replacing or updating the database:
shell%
-.. note:: If the database file exists, and the *-update* flag was not
+.. note::
+
+ If the database file exists, and the *-update* flag was not
given, *kdb5_util* will overwrite the existing database.
Using kdb5_util to upgrade a master KDC from krb5 1.1.x:
@@ -390,7 +398,9 @@ The use of old-kdb-dump.ov for an extra dump and load is necessary
to preserve per-principal policy information, which is not included in
the default dump format of krb5 1.1.x.
-.. note:: Using kdb5_util to dump and reload the principal database is
+.. note::
+
+ Using kdb5_util to dump and reload the principal database is
only necessary when upgrading from versions of krb5 prior
to 1.2.0---newer versions will use the existing database as-is.
@@ -646,14 +656,18 @@ would run the following commands on the KDCs in both realms::
Enter password for principal krbtgt/EXAMPLE.COM@ATHENA.MIT.EDU:
kadmin:
-.. note:: Even if most principals in a realm are generally created
+.. note::
+
+ Even if most principals in a realm are generally created
with the **requires_preauth** flag enabled, this flag is not
desirable on cross-realm authentication keys because doing
so makes it impossible to disable preauthentication on a
service-by-service basis. Disabling it as in the example
above is recommended.
-.. note:: It is very important that these principals have good
+.. note::
+
+ It is very important that these principals have good
passwords. MIT recommends that TGT principal passwords be
at least 26 characters of random ASCII text.
@@ -678,7 +692,9 @@ database as well as the new key. For example::
kadmin: change_password -randkey -keepold krbtgt/ATHENA.MIT.EDU@ATHENA.MIT.EDU
-.. warning:: After issuing this command, the old key is still valid
+.. warning::
+
+ After issuing this command, the old key is still valid
and is still vulnerable to (for instance) brute force
attacks. To completely retire an old key or encryption
type, run the kadmin **purgekeys** command to delete keys
diff --git a/doc/admin/install_kdc.rst b/doc/admin/install_kdc.rst
index 3d0d0f1f44..77d78e14d4 100644
--- a/doc/admin/install_kdc.rst
+++ b/doc/admin/install_kdc.rst
@@ -16,6 +16,7 @@ one of the slaves if necessary (see :ref:`switch_master_slave`). This
installation procedure is based on that recommendation.
.. warning::
+
- The Kerberos system relies on the availability of correct time
information. Ensure that the master and all slave KDCs have
properly synchronized clocks.
@@ -34,7 +35,9 @@ Install and configure the master KDC
Install Kerberos either from the OS-provided packages or from the
source (See :ref:`do_build`).
-.. note:: For the purpose of this document we will use the following
+.. note::
+
+ For the purpose of this document we will use the following
names::
kerberos.mit.edu - master KDC
@@ -131,7 +134,9 @@ An example kdc.conf file::
Replace ``ATHENA.MIT.EDU`` and ``kerberos.mit.edu`` with the name of
your Kerberos realm and server respectively.
-.. note:: You have to have write permission on the target directories
+.. note::
+
+ You have to have write permission on the target directories
(these directories must exist) used by **database_name**,
**key_stash_file**, and **acl_file**.
@@ -144,7 +149,9 @@ Create the KDC database
You will use the :ref:`kdb5_util(8)` command on the master KDC to
create the Kerberos database and the optional :ref:`stash_definition`.
-.. note:: If you choose not to install a stash file, the KDC will
+.. note::
+
+ If you choose not to install a stash file, the KDC will
prompt you for the master key each time it starts up. This
means that the KDC will not be able to start automatically,
such as after a system reboot.
@@ -251,7 +258,9 @@ do so, type::
Each server daemon will fork and run in the background.
-.. note:: Assuming you want these daemons to start up automatically at
+.. note::
+
+ Assuming you want these daemons to start up automatically at
boot time, you can add them to the KDC's ``/etc/rc`` or
``/etc/inittab`` file. You need to have a
:ref:`stash_definition` in order to do this.
@@ -280,7 +289,9 @@ Install the slave KDCs
You are now ready to start configuring the slave KDCs.
-.. note:: Assuming you are setting the KDCs up so that you can easily
+.. note::
+
+ Assuming you are setting the KDCs up so that you can easily
switch the master KDC with one of the slaves, you should
perform each of these steps on the master KDC as well as the
slave KDCs, unless these instructions specify otherwise.
@@ -358,7 +369,9 @@ the KDCs::
host/kerberos.mit.edu@ATHENA.MIT.EDU
host/kerberos-1.mit.edu@ATHENA.MIT.EDU
-.. note:: If you expect that the master and slave KDCs will be
+.. note::
+
+ If you expect that the master and slave KDCs will be
switched at some point of time, list the host principals
from all participating KDC servers in kpropd.acl files on
all of the KDCs. Otherwise, you only need to list the
@@ -408,7 +421,9 @@ following example::
You will need a script to dump and propagate the database. The
following is an example of a Bourne shell script that will do this.
-.. note:: Remember that you need to replace ``/usr/local/var/krb5kdc``
+.. note::
+
+ Remember that you need to replace ``/usr/local/var/krb5kdc``
with the name of the KDC state directory.
::
@@ -442,13 +457,17 @@ Propagation failed?
.. _prop_failed_start:
-.. error:: kprop: No route to host while connecting to server
+.. error::
+
+ kprop: No route to host while connecting to server
Make sure that the hostname of the slave (as given to kprop) is
correct, and that any firewalls beween the master and the slave allow
a connection on port 754.
-.. error:: kprop: Connection refused in call to connect while opening
+.. error::
+
+ kprop: Connection refused in call to connect while opening
connection
If the slave is intended to run kpropd out of inetd, make sure that
@@ -457,7 +476,9 @@ to be restarted or sent a SIGHUP to recognize the new configuration.
If the slave is intended to run kpropd in standalone mode, make sure
that it is running.
-.. error:: kprop: Server rejected authentication while authenticating
+.. error::
+
+ kprop: Server rejected authentication while authenticating
to server
Make sure that:
diff --git a/doc/admin/troubleshoot.rst b/doc/admin/troubleshoot.rst
index 7dc25795d8..3e1cbd64f5 100644
--- a/doc/admin/troubleshoot.rst
+++ b/doc/admin/troubleshoot.rst
@@ -31,10 +31,14 @@ of the :ref:`kvno(1)` command::
List
----
-.. error:: KDC has no support for encryption type while getting
+.. error::
+
+ KDC has no support for encryption type while getting
initial credentials
-.. error:: credential verification failed: KDC has no support for
+.. error::
+
+ credential verification failed: KDC has no support for
encryption type
This most commonly happens when trying to use a principal with only
diff --git a/doc/appdev/gssapi.rst b/doc/appdev/gssapi.rst
index 29c06b565c..a8c731bd7b 100644
--- a/doc/appdev/gssapi.rst
+++ b/doc/appdev/gssapi.rst
@@ -145,16 +145,22 @@ the default keytab. If the input name contains both a *service* and a
*hostname*, clients will be allowed to authenticate to any host-based
principal for the named service and hostname, regardless of realm.
-.. note:: If a *hostname* is specified, it will be canonicalized
+.. note::
+
+ If a *hostname* is specified, it will be canonicalized
using forward name resolution, and possibly also using
reverse name resolution depending on the value of the
**rdns** variable in :ref:`libdefaults`.
-.. note:: If the **ignore_acceptor_hostname** variable in
+.. note::
+
+ If the **ignore_acceptor_hostname** variable in
:ref:`libdefaults` is enabled, then *hostname* will be
ignored even if one is specified in the input name.
-.. note:: In MIT krb5 versions prior to 1.10, and in Heimdal's
+.. note::
+
+ In MIT krb5 versions prior to 1.10, and in Heimdal's
implementation of the krb5 mechanism, an input name with
just a *service* is treated like an input name of
``service@localhostname``, where *localhostname* is the
diff --git a/doc/basic/date_format.rst b/doc/basic/date_format.rst
index bb89251444..f9460feb9b 100644
--- a/doc/basic/date_format.rst
+++ b/doc/basic/date_format.rst
@@ -23,6 +23,7 @@ Here *N* denotes a number, *d* - days, *h* - hours, *m* - minutes,
*s* - seconds.
.. note::
+
The time interval should not exceed 2147483647 seconds.
Examples::
@@ -133,6 +134,7 @@ Abbreviations used in this document
| *z* : numeric time zone;
.. note::
+
- If the date specification contains spaces, you may need to
enclose it in double quotes;
- All keywords are case-insensitive.
diff --git a/doc/basic/stash_file_def.rst b/doc/basic/stash_file_def.rst
index cd6cca47b2..256e2c272d 100644
--- a/doc/basic/stash_file_def.rst
+++ b/doc/basic/stash_file_def.rst
@@ -17,7 +17,9 @@ The file should not be part of any backup of the machine, unless
access to the backup data is secured as tightly as access to the
master password itself.
-.. note:: If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up.
+.. note::
+
+ If you choose not to install a stash file, the KDC will prompt you for the master key each time it starts up.
This means that the KDC will not be able to start automatically, such as after a system reboot.
diff --git a/doc/plugindev/profile.rst b/doc/plugindev/profile.rst
index 671d4c18c2..7dbfdbfc98 100644
--- a/doc/plugindev/profile.rst
+++ b/doc/plugindev/profile.rst
@@ -6,7 +6,9 @@ configuration information is obtained by the Kerberos library and
applications. For a detailed description of the profile interface,
see the header file ``<profile.h>``.
-.. note:: The profile interface does not follow the normal conventions
+.. note::
+
+ The profile interface does not follow the normal conventions
for MIT krb5 pluggable interfaces, because it is part of a
lower-level component of the krb5 library.
diff --git a/doc/tools/func_document.tmpl b/doc/tools/func_document.tmpl
index b9b63d1151..49860589f8 100644
--- a/doc/tools/func_document.tmpl
+++ b/doc/tools/func_document.tmpl
@@ -82,11 +82,13 @@ $function.long_description
#if $function.warn_description is not None
.. warning::
+
$function.warn_description
#end if
#if $function.notes_description is not None
.. note::
+
$function.notes_description
#end if
@@ -94,6 +96,7 @@ $function.long_description
#if $function.version_num is not None
.. note::
+
$function.version_num
#end if
diff --git a/doc/user/tkt_mgmt.rst b/doc/user/tkt_mgmt.rst
index 0ca95accdf..1d5f23701f 100644
--- a/doc/user/tkt_mgmt.rst
+++ b/doc/user/tkt_mgmt.rst
@@ -161,7 +161,9 @@ type::
Password for david@EXAMPLE.COM: <-- [Type david's password here.]
shell%
-.. note:: You cannot mix units; specifying a lifetime of 3h30m would
+.. note::
+
+ You cannot mix units; specifying a lifetime of 3h30m would
result in an error. Note also that most systems specify a
maximum ticket lifetime. If you request a longer ticket
lifetime, it will be automatically truncated to the maximum
diff --git a/doc/user/user_commands/ksu.rst b/doc/user/user_commands/ksu.rst
index aa22c18a3c..d1a8091b2a 100644
--- a/doc/user/user_commands/ksu.rst
+++ b/doc/user/user_commands/ksu.rst
@@ -34,7 +34,9 @@ ksu is a Kerberized version of the su program that has two missions:
one is to securely change the real and effective user ID to that of
the target user, and the other is to create a new security context.
-.. note:: For the sake of clarity, all references to and attributes of
+.. note::
+
+ For the sake of clarity, all references to and attributes of
the user invoking the program will start with "source"
(e.g., "source user", "source cache", etc.).
@@ -151,7 +153,9 @@ not provided (user hit return) ksu continues in a normal mode of
operation (the target cache will not contain the desired TGT). If the
wrong password is typed in, ksu fails.
-.. note:: During authentication, only the tickets that could be
+.. note::
+
+ During authentication, only the tickets that could be
obtained without providing a password are cached in in the
source cache.
generated by cgit (git 2.34.1) at 2024-06-08 15:02:27 +0000