svn rev #25109: trunk/doc/rst_source/krb_admins/ admin_commands/ database/db_operations/
tsitkova@MIT.EDU
tsitkova at MIT.EDU
Mon Aug 22 12:54:20 EDT 2011
http://src.mit.edu/fisheye/changelog/krb5/?cs=25109
Commit By: tsitkova
Log Message:
Removed repetitive text from "Operations on the Kerberos database" sub-section of database administration section. Reference to kdb5_util commands documentation instead.
Changed Files:
U trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
U trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst
U trunk/doc/rst_source/krb_admins/database/db_operations/create_destroy_db.rst
U trunk/doc/rst_source/krb_admins/database/db_operations/create_stash.rst
U trunk/doc/rst_source/krb_admins/database/db_operations/db2file.rst
U trunk/doc/rst_source/krb_admins/database/db_operations/file2db.rst
U trunk/doc/rst_source/krb_admins/database/db_operations/index.rst
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kadmin_local.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -858,8 +858,3 @@
kerberos(1), kpasswd(1), kadmind(8)
-BUGS
---------
-
-Command output needs to be cleaned up.
-
Modified: trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/admin_commands/kdb5_util.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -5,6 +5,8 @@
SYNOPSIS
---------------
+
+.. _kdb5_util_synopsys:
**kdb5_util**
[**-r** *realm*]
@@ -16,6 +18,8 @@
[**-m**]
*command* [*command_options*]
+.. _kdb5_util_synopsys_end:
+
DESCRIPTION
---------------
@@ -32,6 +36,8 @@
COMMAND-LINE OPTIONS
----------------------
+.. _kdb5_util_options:
+
**-r** *realm*
specifies the Kerberos realm of the database; by default the realm returned by krb5_default_local_realm(3) is used.
@@ -57,20 +63,36 @@
**-P** *password*
specifies the master database password. This option is not recommended.
+.. _kdb5_util_options_end:
+
COMMANDS
---------------
+.. _kdb5_util_create:
+
**create** [**-s**]
Creates a new database. If the *-s* option is specified, the stash file is also created. This command fails if the database already exists.
If the command is successful, the database is opened just as if it had already existed when the program was first run.
+.. _kdb5_util_create_end:
+
+.. _kdb5_util_destroy:
+
**destroy** [**-f**]
Destroys the database, first overwriting the disk sectors and then unlinking the files, after prompting the user for confirmation.
With the *-f* argument, does not prompt the user.
+.. _kdb5_util_destroy_end:
+
+.. _kdb5_util_stash:
+
**stash** [**-f** *keyfile*]
Stores the master principal's keys in a stash file. The *-f* argument can be used to override the *keyfile* specified at startup.
+.. _kdb5_util_stash_end:
+
+.. _kdb5_util_dump:
+
**dump** [**-old|-b6|-b7|-ov|-r13**] [**-verbose**] [**-mkey_convert**] [**-new_mkey_file** *mkey_file*] [**-rev**] [**-recurse**] [*filename* [*principals*...]]
Dumps the current Kerberos and KADM5 database into an ASCII file. By default, the database is dumped in current format, "*kdb5_util*
load_dump version 6". If filename is not specified, or is the string "-", the dump is sent to standard output. Options:
@@ -86,7 +108,7 @@
This was the dump format produced on releases prior to 1.2.2.
**-ov**
- causes the dump to be in ovsec_adm_export format.
+ causes the dump to be in *ovsec_adm_export* format.
**-r13**
causes the dump to be in the Kerberos 5 1.3 format ("*kdb5_util* load_dump version 5").
@@ -111,7 +133,10 @@
in cases where database corruption has occured.
In cases of such corruption, this option will probably retrieve more principals than the *-rev* option will.
+.. _kdb5_util_dump_end:
+.. _kdb5_util_load:
+
**load** [**-old|-b6|-b7|-ov|-r13**] [**-hash**] [**-verbose**] [**-update**] *filename dbname*
Loads a database dump from the named file into the named database.
Unless the *-old* or *-b6* option is given, the format of the dump file is detected automatically and handled as appropriate.
@@ -139,11 +164,15 @@
causes the name of each principal and policy to be printed as it is dumped.
**-update**
- records from the dump file are added to or updated in the existing database;
- otherwise, a new database is created containing only what is in the dump file and the old one destroyed upon successful completion.
+ records from the dump file are added to or updated in the existing database.
+ (This is useful in conjunction with an *ovsec_adm_export* format dump if you want to preserve per-principal policy information,
+ since the current default format does not contain this data.)
+ Otherwise, a new database is created containing only what is in the dump file and the old one destroyed upon successful completion.
*dbname* is required and overrides the value specified on the command line or the default.
+.. _kdb5_util_load_end:
+
**ark**
Adds a random key.
@@ -168,14 +197,14 @@
Delete master keys from the K/M principal that are not used to protect any principals.
This command can be used to remove old master keys from a K/M principal once all principal keys are protected by a newer master key.
- **-f**
- does not prompt user.
+ **-f**
+ does not prompt user.
- **-n**
- do a dry run, shows master keys that would be purged, does not actually purge any keys.
+ **-n**
+ do a dry run, shows master keys that would be purged, does not actually purge any keys.
- **-v**
- verbose output.
+ **-v**
+ verbose output.
**update_princ_encryption** [**-f**] [**-n**] [**-v**] [*princ-pattern*]
Update all principal records (or only those matching the princ-pattern glob pattern)
Modified: trunk/doc/rst_source/krb_admins/database/db_operations/create_destroy_db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/db_operations/create_destroy_db.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/database/db_operations/create_destroy_db.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -1,18 +1,24 @@
Creating and destroying a Kerberos database
===================================================
-If you need to create a new Kerberos database, use the *kdb5_util create* command. The syntax is::
+If you need to create a new Kerberos database, use the :ref:`kdb5_util(8)` **create** command.
- kdb5_util create [-s]
-
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_create:
+ :end-before: _kdb5_util_create_end:
-If you specify the -s option, kdb5_util will stash a copy of the master key in a stash file. (See :ref:`create_stash`) For example::
+If you need to destroy the current Kerberos database, use the :ref:`kdb5_util(8)` **destroy** command.
+
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_destroy:
+ :end-before: _kdb5_util_destroy_end:
+
+EXAMPLES::
+
shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU create -s
- kdb5_util: No such file or directory while setting active database to
- => '/usr/local/var/krb5kdc/principal'
- Initializing database '/usr/local/var/krb5kdc/principal' for
- => realm 'ATHENA.MIT.EDU',
+ kdb5_util: No such file or directory while setting active database to'/usr/local/var/krb5kdc/principal'
+ Initializing database '/usr/local/var/krb5kdc/principal' for realm 'ATHENA.MIT.EDU',
master key name 'K/M at ATHENA.MIT.EDU'
You will be prompted for the database Master Password.
It is important that you NOT FORGET this password.
@@ -21,20 +27,9 @@
shell%
-If you need to destroy the current Kerberos database, use the *kdb5_util destroy* command. The syntax is::
-
- kdb5_util destroy [-f]
-
-
-The *destroy* command destroys the database, first overwriting the disk sectors and then unlinking the files. If you specify the *-f* option, *kdb5_util* will not prompt you for a confirmation before destroying the database.
-
-::
-
shell% /usr/local/sbin/kdb5_util -r ATHENA.MIT.EDU destroy
- kdb5_util: Deleting KDC database stored in /usr/local/var/krb5kdc/principal, are you sure
- (type yes to confirm)? <== yes
+ kdb5_util: Deleting KDC database stored in /usr/local/var/krb5kdc/principal, are you sure (type yes to confirm)? <== yes
OK, deleting database '/usr/local/var/krb5kdc/principal'...
-
shell%
------------
Modified: trunk/doc/rst_source/krb_admins/database/db_operations/create_stash.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/db_operations/create_stash.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/database/db_operations/create_stash.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -1,17 +1,20 @@
.. _create_stash:
-Creating a Stash File
+Creating a stash file
============================
A stash file allows a KDC to authenticate itself to the database utilities, such as *kadmin, kadmind, krb5kdc*, and *kdb5_util*.
-To create a stash file, use the *kdb5_util stash* command. The syntax is::
+To create a stash file, use the :ref:`kdb5_util(8)` *stash* command.
- kdb5_util stash [-f keyfile]
-
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_stash:
+ :end-before: _kdb5_util_stash_end:
-For example::
+
+EXAMPLE::
+
shell% kdb5_util stash
kdb5_util: Cannot find/read stored master key while reading master key
kdb5_util: Warning: proceeding without master key
@@ -19,7 +22,7 @@
shell%
-If you do not specify a stash file, *kdb5_util* will stash the key in the file specified in your *kdc.conf* file.
+If you do not specify a stash file, *kdb5_util* will stash the key in the file specified in your :ref:`kdc.conf` file.
Modified: trunk/doc/rst_source/krb_admins/database/db_operations/db2file.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/db_operations/db2file.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/database/db_operations/db2file.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -1,30 +1,20 @@
Dumping a Kerberos database to a file
=============================================
-To dump a Kerberos database into a file, use the *kdb5_util dump* command on one of the KDCs. The syntax is:
+To dump a Kerberos database into a file, use the :ref:`kdb5_util(8)` **dump** command on one of the KDCs.
- kdb5_util dump [-old] [-b6] [-b7] [-ov]
- [-verbose] [-mkey_convert] [-new_mkey_file] [filename
- [principals...]]
-
-The kdb5_util dump command takes the following options
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_dump:
+ :end-before: _kdb5_util_dump_end:
-================= ============================================================
--old Causes the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
--b6 Causes the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
--b7 Causes the dump to be in the Kerberos 5 Beta 7 format ("kdbt_edit load_dump version 4").
--ov Causes the dump to be in ovsec_adm_export format. Currently, the only way to preserve per-principal policy information is to use this in conjunction with a normal dump.
--verbose Causes the name of each principal and policy to be printed as it is dumped.
--mkey_convert Prompts for a new master password, and then dumps the database with all keys reencrypted in this new master key
--new_mkey_file Reads a new key from the default keytab and then dumps the database with all keys reencrypted in this new master key
-================= ============================================================
-For example::
+
+EXAMPLES::
+
shell% kdb5_util dump dumpfile
shell%
-
shell% kbd5_util dump -verbose dumpfile
kadmin/admin at ATHENA.MIT.EDU
@@ -35,10 +25,9 @@
shell%
-If you specify which principals to dump, you must use the full principal, as in the following example. (The line beginning with => is a continuation of the previous line.)::
+If you specify which principals to dump, you must use the full principal, as in the following example::
- shell% kdb5_util dump -verbose dumpfile K/M at ATHENA.MIT.EDU
- => kadmin/admin at ATHENA.MIT.EDU
+ shell% kdb5_util dump -verbose dumpfile K/M at ATHENA.MIT.EDU kadmin/admin at ATHENA.MIT.EDU
kadmin/admin at ATHENA.MIT.EDU
K/M at ATHENA.MIT.EDU
shell%
Modified: trunk/doc/rst_source/krb_admins/database/db_operations/file2db.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/db_operations/file2db.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/database/db_operations/file2db.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -4,26 +4,15 @@
Restoring a Kerberos database from a dump file
================================================
-To restore a Kerberos database dump from a file, use the *kdb5_util load* command on one of the KDCs. The syntax is::
+To restore a Kerberos database dump from a file, use the :ref:`kdb5_util(8)` **load** command on one of the KDCs.
- kdb5_util load [-old] [-b6] [-b7] [-ov] [-verbose]
- [-update] [-hash] dumpfilename dbname [admin_dbname]
-
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_load:
+ :end-before: _kdb5_util_load_end:
-The kdb5_util load command takes the following options
-==================== ===========================================================
--old Requires the dump to be in the Kerberos 5 Beta 5 and earlier dump format ("kdb5_edit load_dump version 2.0").
--b6 Requires the dump to be in the Kerberos 5 Beta 6 format ("kdb5_edit load_dump version 3.0").
--b7 Requires the dump to be in the Kerberos 5 Beta 7 format ("kdb5_edit load_dump version 4").
--ov Requires the dump to be in ovsec_adm_export format.
--verbose Causes the name of each principal and policy to be printed as it is loaded.
--update Causes records from the dump file to be updated in or added to the existing database. This is useful in conjunction with an ovsec_adm_export format dump if you want to preserve per-principal policy information, since the current default format does not contain this data.
--hash Causes the database to be stored as a hash rather than a binary tree.
-==================== ===========================================================
+EXAMPLES::
-For example::
-
shell% kdb5_util load dumpfile principal
shell%
@@ -32,7 +21,7 @@
shell%
-If the database file exists, and the *-update* flag was not given, kdb5_util will overwrite the existing database.
+.. note:: If the database file exists, and the *-update* flag was not given, *kdb5_util* will overwrite the existing database.
------------
Modified: trunk/doc/rst_source/krb_admins/database/db_operations/index.rst
===================================================================
--- trunk/doc/rst_source/krb_admins/database/db_operations/index.rst 2011-08-20 20:26:09 UTC (rev 25108)
+++ trunk/doc/rst_source/krb_admins/database/db_operations/index.rst 2011-08-22 16:54:20 UTC (rev 25109)
@@ -3,36 +3,26 @@
Operations on the Kerberos database
=============================================
-The *kdb5_util command* is the primary tool for administrating the Kerberos database. The syntax is::
+The :ref:`kdb5_util(8)` command is the primary tool for administrating the Kerberos database.
- kdb5_util command [kdb5_util_options] [command_options]
-
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_synopsys:
+ :end-before: _kdb5_util_synopsys_end:
-The *kdb5_util command* takes the following options, which **override the defaults** specified in the configuration files:
+**OPTIONS**
-========================== =============================================================
--r *realm* Specifies the the Kerberos realm of the database.
--d *database_name* Specifies the name under which the principal database is stored.
--k *master_key_type* Specifies the key type of the master key in the database.
--M *master_key_name* Specifies the principal name of the master key in the database.
--m Indicates that the master database password should be read from the TTY rather than fetched from a file on disk.
--sf *stash_file* Specifies the stash file of the master database password
--P *password* Specifies the master database password. MIT does not recommend using this option.
-========================== =============================================================
+.. include:: ../../admin_commands/kdb5_util.rst
+ :start-after: _kdb5_util_options:
+ :end-before: _kdb5_util_options_end:
-|
-
.. toctree::
:maxdepth: 1
-
db2file.rst
file2db.rst
create_stash.rst
create_destroy_db.rst
-
-
------------
Feedback:
More information about the cvs-krb5
mailing list