invoke-ntp-keygen.texi revision 330106
1@node ntp-keygen Invocation 2@section Invoking ntp-keygen 3@pindex ntp-keygen 4@cindex Create a NTP host key 5@ignore 6# 7# EDIT THIS FILE WITH CAUTION (invoke-ntp-keygen.texi) 8# 9# It has been AutoGen-ed February 27, 2018 at 05:15:57 PM by AutoGen 5.18.5 10# From the definitions ntp-keygen-opts.def 11# and the template file agtexi-cmd.tpl 12@end ignore 13 14 15 16This program generates cryptographic data files used by the NTPv4 17authentication and identification schemes. 18It can generate message digest keys used in symmetric key cryptography and, 19if the OpenSSL software library has been installed, it can generate host keys, 20signing keys, certificates, and identity keys and parameters used in Autokey 21public key cryptography. 22These files are used for cookie encryption, 23digital signature, and challenge/response identification algorithms 24compatible with the Internet standard security infrastructure. 25 26The message digest symmetric keys file is generated in a format 27compatible with NTPv3. 28All other files are in PEM-encoded printable ASCII format, 29so they can be embedded as MIME attachments in email to other sites 30and certificate authorities. 31By default, files are not encrypted. 32 33When used to generate message digest symmetric keys, the program 34produces a file containing ten pseudo-random printable ASCII strings 35suitable for the MD5 message digest algorithm included in the 36distribution. 37If the OpenSSL library is installed, it produces an additional ten 38hex-encoded random bit strings suitable for SHA1, AES-128-CMAC, and 39other message digest algorithms. 40The message digest symmetric keys file must be distributed and stored 41using secure means beyond the scope of NTP itself. 42Besides the keys used for ordinary NTP associations, additional keys 43can be defined as passwords for the 44@code{ntpq(1ntpqmdoc)} 45and 46@code{ntpdc(1ntpdcmdoc)} 47utility programs. 48 49The remaining generated files are compatible with other OpenSSL 50applications and other Public Key Infrastructure (PKI) resources. 51Certificates generated by this program are compatible with extant 52industry practice, although some users might find the interpretation of 53X509v3 extension fields somewhat liberal. 54However, the identity keys are probably not compatible with anything 55other than Autokey. 56 57Some files used by this program are encrypted using a private password. 58The 59@code{-p} 60option specifies the read password for local encrypted files and the 61@code{-q} 62option the write password for encrypted files sent to remote sites. 63If no password is specified, the host name returned by the Unix 64@code{hostname(1)} 65command, normally the DNS name of the host, is used as the the default read 66password, for convenience. 67The 68@code{ntp-keygen} 69program prompts for the password if it reads an encrypted file 70and the password is missing or incorrect. 71If an encrypted file is read successfully and 72no write password is specified, the read password is used 73as the write password by default. 74 75The 76@code{pw} 77option of the 78@code{crypto} 79@code{ntpd(1ntpdmdoc)} 80configuration command specifies the read 81password for previously encrypted local files. 82This must match the local read password used by this program. 83If not specified, the host name is used. 84Thus, if files are generated by this program without an explicit password, 85they can be read back by 86@code{ntpd(1ntpdmdoc)} 87without specifying an explicit password but only on the same host. 88If the write password used for encryption is specified as the host name, 89these files can be read by that host with no explicit password. 90 91Normally, encrypted files for each host are generated by that host and 92used only by that host, although exceptions exist as noted later on 93this page. 94The symmetric keys file, normally called 95@file{ntp.keys}, 96is usually installed in 97@file{/etc}. 98Other files and links are usually installed in 99@file{/usr/local/etc}, 100which is normally in a shared filesystem in 101NFS-mounted networks and cannot be changed by shared clients. 102In these cases, NFS clients can specify the files in another 103directory such as 104@file{/etc} 105using the 106@code{keysdir} 107@code{ntpd(1ntpdmdoc)} 108configuration file command. 109 110This program directs commentary and error messages to the standard 111error stream 112@file{stderr} 113and remote files to the standard output stream 114@file{stdout} 115where they can be piped to other applications or redirected to files. 116The names used for generated files and links all begin with the 117string 118@file{ntpkey*} 119and include the file type, generating host and filestamp, 120as described in the 121@ref{Cryptographic Data Files} 122section below. 123 124@subsubsection Running the Program 125The safest way to run the 126@code{ntp-keygen} 127program is logged in directly as root. 128The recommended procedure is change to the 129@kbd{keys} 130directory, usually 131@file{/usr/local/etc}, 132then run the program. 133 134To test and gain experience with Autokey concepts, log in as root and 135change to the 136@kbd{keys} 137directory, usually 138@file{/usr/local/etc}. 139When run for the first time, or if all files with names beginning with 140@file{ntpkey*} 141have been removed, use the 142@code{ntp-keygen} 143command without arguments to generate a default 144@code{RSA} 145host key and matching 146@code{RSA-MD5} 147certificate file with expiration date one year hence, 148which is all that is necessary in many cases. 149The program also generates soft links from the generic names 150to the respective files. 151If run again without options, the program uses the 152existing keys and parameters and generates a new certificate file with 153new expiration date one year hence, and soft link. 154 155The host key is used to encrypt the cookie when required and so must be 156@code{RSA} 157type. 158By default, the host key is also the sign key used to encrypt signatures. 159When necessary, a different sign key can be specified and this can be 160either 161@code{RSA} 162or 163@code{DSA} 164type. 165By default, the message digest type is 166@code{MD5}, 167but any combination 168of sign key type and message digest type supported by the OpenSSL library 169can be specified, including those using the 170@code{AES128CMAC}, @code{MD2}, @code{MD5}, @code{MDC2}, @code{SHA}, @code{SHA1} 171and 172@code{RIPE160} 173message digest algorithms. 174However, the scheme specified in the certificate must be compatible 175with the sign key. 176Certificates using any digest algorithm are compatible with 177@code{RSA} 178sign keys; 179however, only 180@code{SHA} 181and 182@code{SHA1} 183certificates are compatible with 184@code{DSA} 185sign keys. 186 187Private/public key files and certificates are compatible with 188other OpenSSL applications and very likely other libraries as well. 189Certificates or certificate requests derived from them should be compatible 190with extant industry practice, although some users might find 191the interpretation of X509v3 extension fields somewhat liberal. 192However, the identification parameter files, although encoded 193as the other files, are probably not compatible with anything other than Autokey. 194 195Running the program as other than root and using the Unix 196@code{su(1)} 197command 198to assume root may not work properly, since by default the OpenSSL library 199looks for the random seed file 200@file{.rnd} 201in the user home directory. 202However, there should be only one 203@file{.rnd}, 204most conveniently 205in the root directory, so it is convenient to define the 206.Ev RANDFILE 207environment variable used by the OpenSSL library as the path to 208@file{.rnd}. 209 210Installing the keys as root might not work in NFS-mounted 211shared file systems, as NFS clients may not be able to write 212to the shared keys directory, even as root. 213In this case, NFS clients can specify the files in another 214directory such as 215@file{/etc} 216using the 217@code{keysdir} 218@code{ntpd(1ntpdmdoc)} 219configuration file command. 220There is no need for one client to read the keys and certificates 221of other clients or servers, as these data are obtained automatically 222by the Autokey protocol. 223 224Ordinarily, cryptographic files are generated by the host that uses them, 225but it is possible for a trusted agent (TA) to generate these files 226for other hosts; however, in such cases files should always be encrypted. 227The subject name and trusted name default to the hostname 228of the host generating the files, but can be changed by command line options. 229It is convenient to designate the owner name and trusted name 230as the subject and issuer fields, respectively, of the certificate. 231The owner name is also used for the host and sign key files, 232while the trusted name is used for the identity files. 233 234All files are installed by default in the keys directory 235@file{/usr/local/etc}, 236which is normally in a shared filesystem 237in NFS-mounted networks. 238The actual location of the keys directory 239and each file can be overridden by configuration commands, 240but this is not recommended. 241Normally, the files for each host are generated by that host 242and used only by that host, although exceptions exist 243as noted later on this page. 244 245Normally, files containing private values, 246including the host key, sign key and identification parameters, 247are permitted root read/write-only; 248while others containing public values are permitted world readable. 249Alternatively, files containing private values can be encrypted 250and these files permitted world readable, 251which simplifies maintenance in shared file systems. 252Since uniqueness is insured by the 253@kbd{hostname} 254and 255@kbd{filestamp} 256file name extensions, the files for an NTP server and 257dependent clients can all be installed in the same shared directory. 258 259The recommended practice is to keep the file name extensions 260when installing a file and to install a soft link 261from the generic names specified elsewhere on this page 262to the generated files. 263This allows new file generations to be activated simply 264by changing the link. 265If a link is present, 266@code{ntpd(1ntpdmdoc)} 267follows it to the file name to extract the 268@kbd{filestamp}. 269If a link is not present, 270@code{ntpd(1ntpdmdoc)} 271extracts the 272@kbd{filestamp} 273from the file itself. 274This allows clients to verify that the file and generation times 275are always current. 276The 277@code{ntp-keygen} 278program uses the same 279@kbd{filestamp} 280extension for all files generated 281at one time, so each generation is distinct and can be readily 282recognized in monitoring data. 283 284Run the command on as many hosts as necessary. 285Designate one of them as the trusted host (TH) using 286@code{ntp-keygen} 287with the 288@code{-T} 289option and configure it to synchronize from reliable Internet servers. 290Then configure the other hosts to synchronize to the TH directly or 291indirectly. 292A certificate trail is created when Autokey asks the immediately 293ascendant host towards the TH to sign its certificate, which is then 294provided to the immediately descendant host on request. 295All group hosts should have acyclic certificate trails ending on the TH. 296 297The host key is used to encrypt the cookie when required and so must be 298RSA type. 299By default, the host key is also the sign key used to encrypt 300signatures. 301A different sign key can be assigned using the 302@code{-S} 303option and this can be either 304@code{RSA} 305or 306@code{DSA} 307type. 308By default, the signature 309message digest type is 310@code{MD5}, 311but any combination of sign key type and 312message digest type supported by the OpenSSL library can be specified 313using the 314@code{-c} 315option. 316 317The rules say cryptographic media should be generated with proventic 318filestamps, which means the host should already be synchronized before 319this program is run. 320This of course creates a chicken-and-egg problem 321when the host is started for the first time. 322Accordingly, the host time 323should be set by some other means, such as eyeball-and-wristwatch, at 324least so that the certificate lifetime is within the current year. 325After that and when the host is synchronized to a proventic source, the 326certificate should be re-generated. 327 328Additional information on trusted groups and identity schemes is on the 329@quotedblleft{}Autokey Public-Key Authentication@quotedblright{} 330page. 331 332File names begin with the prefix 333@file{ntpkey}_ 334and end with the suffix 335@file{_}@kbd{hostname}. @kbd{filestamp}, 336where 337@kbd{hostname} 338is the owner name, usually the string returned 339by the Unix 340@code{hostname(1)} 341command, and 342@kbd{filestamp} 343is the NTP seconds when the file was generated, in decimal digits. 344This both guarantees uniqueness and simplifies maintenance 345procedures, since all files can be quickly removed 346by a 347@code{rm} @file{ntpkey*} 348command or all files generated 349at a specific time can be removed by a 350@code{rm} @file{*}@kbd{filestamp} 351command. 352To further reduce the risk of misconfiguration, 353the first two lines of a file contain the file name 354and generation date and time as comments. 355 356@subsubsection Trusted Hosts and Groups 357Each cryptographic configuration involves selection of a signature scheme 358and identification scheme, called a cryptotype, 359as explained in the 360@ref{Authentication Options} 361section of 362@code{ntp.conf(5)}. 363The default cryptotype uses 364@code{RSA} 365encryption, 366@code{MD5} 367message digest 368and 369@code{TC} 370identification. 371First, configure a NTP subnet including one or more low-stratum 372trusted hosts from which all other hosts derive synchronization 373directly or indirectly. 374Trusted hosts have trusted certificates; 375all other hosts have nontrusted certificates. 376These hosts will automatically and dynamically build authoritative 377certificate trails to one or more trusted hosts. 378A trusted group is the set of all hosts that have, directly or indirectly, 379a certificate trail ending at a trusted host. 380The trail is defined by static configuration file entries 381or dynamic means described on the 382@ref{Automatic NTP Configuration Options} 383section of 384@code{ntp.conf(5)}. 385 386On each trusted host as root, change to the keys directory. 387To insure a fresh fileset, remove all 388@file{ntpkey} 389files. 390Then run 391@code{ntp-keygen} 392@code{-T} 393to generate keys and a trusted certificate. 394On all other hosts do the same, but leave off the 395@code{-T} 396flag to generate keys and nontrusted certificates. 397When complete, start the NTP daemons beginning at the lowest stratum 398and working up the tree. 399It may take some time for Autokey to instantiate the certificate trails 400throughout the subnet, but setting up the environment is completely automatic. 401 402If it is necessary to use a different sign key or different digest/signature 403scheme than the default, run 404@code{ntp-keygen} 405with the 406@code{-S} @kbd{type} 407option, where 408@kbd{type} 409is either 410@code{RSA} 411or 412@code{DSA}. 413The most frequent need to do this is when a 414@code{DSA}-signed 415certificate is used. 416If it is necessary to use a different certificate scheme than the default, 417run 418@code{ntp-keygen} 419with the 420@code{-c} @kbd{scheme} 421option and selected 422@kbd{scheme} 423as needed. 424If 425@code{ntp-keygen} 426is run again without these options, it generates a new certificate 427using the same scheme and sign key, and soft link. 428 429After setting up the environment it is advisable to update certificates 430from time to time, if only to extend the validity interval. 431Simply run 432@code{ntp-keygen} 433with the same flags as before to generate new certificates 434using existing keys, and soft links. 435However, if the host or sign key is changed, 436@code{ntpd(1ntpdmdoc)} 437should be restarted. 438When 439@code{ntpd(1ntpdmdoc)} 440is restarted, it loads any new files and restarts the protocol. 441Other dependent hosts will continue as usual until signatures are refreshed, 442at which time the protocol is restarted. 443 444@subsubsection Identity Schemes 445As mentioned on the Autonomous Authentication page, 446the default 447@code{TC} 448identity scheme is vulnerable to a middleman attack. 449However, there are more secure identity schemes available, 450including 451@code{PC}, @code{IFF}, @code{GQ} 452and 453@code{MV} 454schemes described below. 455These schemes are based on a TA, one or more trusted hosts 456and some number of nontrusted hosts. 457Trusted hosts prove identity using values provided by the TA, 458while the remaining hosts prove identity using values provided 459by a trusted host and certificate trails that end on that host. 460The name of a trusted host is also the name of its sugroup 461and also the subject and issuer name on its trusted certificate. 462The TA is not necessarily a trusted host in this sense, but often is. 463 464In some schemes there are separate keys for servers and clients. 465A server can also be a client of another server, 466but a client can never be a server for another client. 467In general, trusted hosts and nontrusted hosts that operate 468as both server and client have parameter files that contain 469both server and client keys. 470Hosts that operate 471only as clients have key files that contain only client keys. 472 473The PC scheme supports only one trusted host in the group. 474On trusted host alice run 475@code{ntp-keygen} 476@code{-P} 477@code{-p} @kbd{password} 478to generate the host key file 479@file{ntpkey}_ @code{RSA} @file{key_alice.} @kbd{filestamp} 480and trusted private certificate file 481@file{ntpkey}_ @code{RSA-MD5} @code{_} @file{cert_alice.} @kbd{filestamp}, 482and soft links. 483Copy both files to all group hosts; 484they replace the files which would be generated in other schemes. 485On each host 486@kbd{bob} 487install a soft link from the generic name 488@file{ntpkey_host_}@kbd{bob} 489to the host key file and soft link 490@file{ntpkey_cert_}@kbd{bob} 491to the private certificate file. 492Note the generic links are on bob, but point to files generated 493by trusted host alice. 494In this scheme it is not possible to refresh 495either the keys or certificates without copying them 496to all other hosts in the group, and recreating the soft links. 497 498For the 499@code{IFF} 500scheme proceed as in the 501@code{TC} 502scheme to generate keys 503and certificates for all group hosts, then for every trusted host in the group, 504generate the 505@code{IFF} 506parameter file. 507On trusted host alice run 508@code{ntp-keygen} 509@code{-T} 510@code{-I} 511@code{-p} @kbd{password} 512to produce her parameter file 513@file{ntpkey_IFFpar_alice.}@kbd{filestamp}, 514which includes both server and client keys. 515Copy this file to all group hosts that operate as both servers 516and clients and install a soft link from the generic 517@file{ntpkey_iff_alice} 518to this file. 519If there are no hosts restricted to operate only as clients, 520there is nothing further to do. 521As the 522@code{IFF} 523scheme is independent 524of keys and certificates, these files can be refreshed as needed. 525 526If a rogue client has the parameter file, it could masquerade 527as a legitimate server and present a middleman threat. 528To eliminate this threat, the client keys can be extracted 529from the parameter file and distributed to all restricted clients. 530After generating the parameter file, on alice run 531@code{ntp-keygen} 532@code{-e} 533and pipe the output to a file or email program. 534Copy or email this file to all restricted clients. 535On these clients install a soft link from the generic 536@file{ntpkey_iff_alice} 537to this file. 538To further protect the integrity of the keys, 539each file can be encrypted with a secret password. 540 541For the 542@code{GQ} 543scheme proceed as in the 544@code{TC} 545scheme to generate keys 546and certificates for all group hosts, then for every trusted host 547in the group, generate the 548@code{IFF} 549parameter file. 550On trusted host alice run 551@code{ntp-keygen} 552@code{-T} 553@code{-G} 554@code{-p} @kbd{password} 555to produce her parameter file 556@file{ntpkey_GQpar_alice.}@kbd{filestamp}, 557which includes both server and client keys. 558Copy this file to all group hosts and install a soft link 559from the generic 560@file{ntpkey_gq_alice} 561to this file. 562In addition, on each host 563@kbd{bob} 564install a soft link 565from generic 566@file{ntpkey_gq_}@kbd{bob} 567to this file. 568As the 569@code{GQ} 570scheme updates the 571@code{GQ} 572parameters file and certificate 573at the same time, keys and certificates can be regenerated as needed. 574 575For the 576@code{MV} 577scheme, proceed as in the 578@code{TC} 579scheme to generate keys 580and certificates for all group hosts. 581For illustration assume trish is the TA, alice one of several trusted hosts 582and bob one of her clients. 583On TA trish run 584@code{ntp-keygen} 585@code{-V} @kbd{n} 586@code{-p} @kbd{password}, 587where 588@kbd{n} 589is the number of revokable keys (typically 5) to produce 590the parameter file 591@file{ntpkeys_MVpar_trish.}@kbd{filestamp} 592and client key files 593@file{ntpkeys_MVkey}@kbd{d} @kbd{_} @file{trish.} @kbd{filestamp} 594where 595@kbd{d} 596is the key number (0 < 597@kbd{d} 598< 599@kbd{n}). 600Copy the parameter file to alice and install a soft link 601from the generic 602@file{ntpkey_mv_alice} 603to this file. 604Copy one of the client key files to alice for later distribution 605to her clients. 606It does not matter which client key file goes to alice, 607since they all work the same way. 608Alice copies the client key file to all of her clients. 609On client bob install a soft link from generic 610@file{ntpkey_mvkey_bob} 611to the client key file. 612As the 613@code{MV} 614scheme is independent of keys and certificates, 615these files can be refreshed as needed. 616 617@subsubsection Command Line Options 618@table @asis 619@item @code{-b} @code{--imbits}= @kbd{modulus} 620Set the number of bits in the identity modulus for generating identity keys to 621@kbd{modulus} 622bits. 623The number of bits in the identity modulus defaults to 256, but can be set to 624values from 256 to 2048 (32 to 256 octets). 625Use the larger moduli with caution, as this can consume considerable computing 626resources and increases the size of authenticated packets. 627@item @code{-c} @code{--certificate}= @kbd{scheme} 628Select certificate signature encryption/message digest scheme. 629The 630@kbd{scheme} 631can be one of the following: 632@code{RSA-MD2}, @code{RSA-MD5}, @code{RSA-MDC2}, @code{RSA-SHA}, @code{RSA-SHA1}, @code{RSA-RIPEMD160}, @code{DSA-SHA}, 633or 634@code{DSA-SHA1}. 635Note that 636@code{RSA} 637schemes must be used with an 638@code{RSA} 639sign key and 640@code{DSA} 641schemes must be used with a 642@code{DSA} 643sign key. 644The default without this option is 645@code{RSA-MD5}. 646If compatibility with FIPS 140-2 is required, either the 647@code{DSA-SHA} 648or 649@code{DSA-SHA1} 650scheme must be used. 651@item @code{-C} @code{--cipher}= @kbd{cipher} 652Select the OpenSSL cipher to encrypt the files containing private keys. 653The default without this option is three-key triple DES in CBC mode, 654@code{des-ede3-cbc}. 655The 656@code{openssl} @code{-h} 657command provided with OpenSSL displays available ciphers. 658@item @code{-d} @code{--debug-level} 659Increase debugging verbosity level. 660This option displays the cryptographic data produced in eye-friendly billboards. 661@item @code{-D} @code{--set-debug-level}= @kbd{level} 662Set the debugging verbosity to 663@kbd{level}. 664This option displays the cryptographic data produced in eye-friendly billboards. 665@item @code{-e} @code{--id-key} 666Write the 667@code{IFF} 668or 669@code{GQ} 670public parameters from the 671@kbd{IFFkey} @kbd{or} @kbd{GQkey} 672client keys file previously specified 673as unencrypted data to the standard output stream 674@file{stdout}. 675This is intended for automatic key distribution by email. 676@item @code{-G} @code{--gq-params} 677Generate a new encrypted 678@code{GQ} 679parameters and key file for the Guillou-Quisquater (GQ) identity scheme. 680This option is mutually exclusive with the 681@code{-I} 682and 683@code{-V} 684options. 685@item @code{-H} @code{--host-key} 686Generate a new encrypted 687@code{RSA} 688public/private host key file. 689@item @code{-I} @code{--iffkey} 690Generate a new encrypted 691@code{IFF} 692key file for the Schnorr (IFF) identity scheme. 693This option is mutually exclusive with the 694@code{-G} 695and 696Fl V 697options. 698@item @code{-i} @code{--ident}= @kbd{group} 699Set the optional Autokey group name to 700@kbd{group}. 701This is used in the identity scheme parameter file names of 702@code{IFF}, @code{GQ}, 703and 704@code{MV} 705client parameters files. 706In that role, the default is the host name if no group is provided. 707The group name, if specified using 708@code{-i} 709or 710@code{-s} 711following an 712@quoteleft{}@@@quoteright{} 713character, is also used in certificate subject and issuer names in the form 714@kbd{host} @kbd{@@} @kbd{group} 715and should match the group specified via 716@code{crypto} @code{ident} 717or 718@code{server} @code{ident} 719in the ntpd configuration file. 720@item @code{-l} @code{--lifetime}= @kbd{days} 721Set the lifetime for certificate expiration to 722@kbd{days}. 723The default lifetime is one year (365 days). 724@item @code{-m} @code{--modulus}= @kbd{bits} 725Set the number of bits in the prime modulus for generating files to 726@kbd{bits}. 727The modulus defaults to 512, but can be set from 256 to 2048 (32 to 256 octets). 728Use the larger moduli with caution, as this can consume considerable computing 729resources and increases the size of authenticated packets. 730@item @code{-M} @code{--md5key} 731Generate a new symmetric keys file containing 10 732@code{MD5} 733keys, and if OpenSSL is available, 10 734@code{SHA} 735keys. 736An 737@code{MD5} 738key is a string of 20 random printable ASCII characters, while a 739@code{SHA} 740key is a string of 40 random hex digits. 741The file can be edited using a text editor to change the key type or key content. 742This option is mutually exclusive with all other options. 743@item @code{-p} @code{--password}= @kbd{passwd} 744Set the password for reading and writing encrypted files to 745@kbd{passwd}. 746These include the host, sign and identify key files. 747By default, the password is the string returned by the Unix 748@code{hostname} 749command. 750@item @code{-P} @code{--pvt-cert} 751Generate a new private certificate used by the 752@code{PC} 753identity scheme. 754By default, the program generates public certificates. 755Note: the PC identity scheme is not recommended for new installations. 756@item @code{-q} @code{--export-passwd}= @kbd{passwd} 757Set the password for writing encrypted 758@code{IFF}, @code{GQ} @code{and} @code{MV} 759identity files redirected to 760@file{stdout} 761to 762@kbd{passwd}. 763In effect, these files are decrypted with the 764@code{-p} 765password, then encrypted with the 766@code{-q} 767password. 768By default, the password is the string returned by the Unix 769@code{hostname} 770command. 771@item @code{-s} @code{--subject-key}= @code{[host]} @code{[@@ @kbd{group}]} 772Specify the Autokey host name, where 773@kbd{host} 774is the optional host name and 775@kbd{group} 776is the optional group name. 777The host name, and if provided, group name are used in 778@kbd{host} @kbd{@@} @kbd{group} 779form as certificate subject and issuer. 780Specifying 781@code{-s} @code{-@@} @kbd{group} 782is allowed, and results in leaving the host name unchanged, as with 783@code{-i} @kbd{group}. 784The group name, or if no group is provided, the host name are also used in the 785file names of 786@code{IFF}, @code{GQ}, 787and 788@code{MV} 789identity scheme client parameter files. 790If 791@kbd{host} 792is not specified, the default host name is the string returned by the Unix 793@code{hostname} 794command. 795@item @code{-S} @code{--sign-key}= @code{[@code{RSA} | @code{DSA}]} 796Generate a new encrypted public/private sign key file of the specified type. 797By default, the sign key is the host key and has the same type. 798If compatibility with FIPS 140-2 is required, the sign key type must be 799@code{DSA}. 800@item @code{-T} @code{--trusted-cert} 801Generate a trusted certificate. 802By default, the program generates a non-trusted certificate. 803@item @code{-V} @code{--mv-params} @kbd{nkeys} 804Generate 805@kbd{nkeys} 806encrypted server keys and parameters for the Mu-Varadharajan (MV) 807identity scheme. 808This option is mutually exclusive with the 809@code{-I} 810and 811@code{-G} 812options. 813Note: support for this option should be considered a work in progress. 814@end table 815 816@subsubsection Random Seed File 817All cryptographically sound key generation schemes must have means 818to randomize the entropy seed used to initialize 819the internal pseudo-random number generator used 820by the library routines. 821The OpenSSL library uses a designated random seed file for this purpose. 822The file must be available when starting the NTP daemon and 823@code{ntp-keygen} 824program. 825If a site supports OpenSSL or its companion OpenSSH, 826it is very likely that means to do this are already available. 827 828It is important to understand that entropy must be evolved 829for each generation, for otherwise the random number sequence 830would be predictable. 831Various means dependent on external events, such as keystroke intervals, 832can be used to do this and some systems have built-in entropy sources. 833Suitable means are described in the OpenSSL software documentation, 834but are outside the scope of this page. 835 836The entropy seed used by the OpenSSL library is contained in a file, 837usually called 838@file{.rnd}, 839which must be available when starting the NTP daemon 840or the 841@code{ntp-keygen} 842program. 843The NTP daemon will first look for the file 844using the path specified by the 845@code{randfile} 846subcommand of the 847@code{crypto} 848configuration command. 849If not specified in this way, or when starting the 850@code{ntp-keygen} 851program, 852the OpenSSL library will look for the file using the path specified 853by the 854.Ev RANDFILE 855environment variable in the user home directory, 856whether root or some other user. 857If the 858.Ev RANDFILE 859environment variable is not present, 860the library will look for the 861@file{.rnd} 862file in the user home directory. 863Since both the 864@code{ntp-keygen} 865program and 866@code{ntpd(1ntpdmdoc)} 867daemon must run as root, the logical place to put this file is in 868@file{/.rnd} 869or 870@file{/root/.rnd}. 871If the file is not available or cannot be written, 872the daemon exits with a message to the system log and the program 873exits with a suitable error message. 874 875@subsubsection Cryptographic Data Files 876All file formats begin with two nonencrypted lines. 877The first line contains the file name, including the generated host name 878and filestamp, in the format 879@file{ntpkey_}@kbd{key} @kbd{_} @kbd{name}. @kbd{filestamp}, 880where 881@kbd{key} 882is the key or parameter type, 883@kbd{name} 884is the host or group name and 885@kbd{filestamp} 886is the filestamp (NTP seconds) when the file was created. 887By convention, 888@kbd{key} 889names in generated file names include both upper and lower case 890characters, while 891@kbd{key} 892names in generated link names include only lower case characters. 893The filestamp is not used in generated link names. 894The second line contains the datestamp in conventional Unix 895@file{date} 896format. 897Lines beginning with 898@quoteleft{}#@quoteright{} 899are considered comments and ignored by the 900@code{ntp-keygen} 901program and 902@code{ntpd(1ntpdmdoc)} 903daemon. 904 905The remainder of the file contains cryptographic data, encoded first using ASN.1 906rules, then encrypted if necessary, and finally written in PEM-encoded 907printable ASCII text, preceded and followed by MIME content identifier lines. 908 909The format of the symmetric keys file, ordinarily named 910@file{ntp.keys}, 911is somewhat different than the other files in the interest of backward compatibility. 912Ordinarily, the file is generated by this program, but it can be constructed 913and edited using an ordinary text editor. 914@verbatim 915# ntpkey_MD5key_bk.ntp.org.3595864945 916# Thu Dec 12 19:22:25 2013 917 9181 MD5 L";Nw<\`.I<f4U0)247"i # MD5 key 9192 MD5 &>l0%XXK9O'51VwV<xq~ # MD5 key 9203 MD5 lb4zLW~d^!K:]RsD'qb6 # MD5 key 9214 MD5 Yue:tL[+vR)M\`n~bY,'? # MD5 key 9225 MD5 B;fx'Kgr/&4ZTbL6=RxA # MD5 key 9236 MD5 4eYwa\`o@}3i@@@@V@@..R9!l # MD5 key 9247 MD5 \`A.([h+;wTQ|xfi%Sn_! # MD5 key 9258 MD5 45:V,r4]l6y^JH6"Sh?F # MD5 key 9269 MD5 3-5vcn*6l29DS?Xdsg)* # MD5 key 92710 MD5 2late4Me # MD5 key 92811 SHA1 a27872d3030a9025b8446c751b4551a7629af65c # SHA1 key 92912 SHA1 21bc3b4865dbb9e920902abdccb3e04ff97a5e74 # SHA1 key 93013 SHA1 2b7736fe24fef5ba85ae11594132ab5d6f6daba9 # SHA1 key 93114 SHA a5332809c8878dd3a5b918819108a111509aeceb # SHA key 93215 MD2 2fe16c88c760ff2f16d4267e36c1aa6c926e6964 # MD2 key 93316 MD4 b2691811dc19cfc0e2f9bcacd74213f29812183d # MD4 key 93417 MD5 e4d6735b8bdad58ec5ffcb087300a17f7fef1f7c # MD5 key 93518 MDC2 a8d5e2315c025bf3a79174c87fbd10477de2eabc # MDC2 key 93619 RIPEMD160 77ca332cafb30e3cafb174dcd5b80ded7ba9b3d2 # RIPEMD160 key 93720 AES128CMAC f92ff73eee86c1e7dc638d6489a04e4e555af878 # AES128CMAC key 938@end verbatim 939@example 940Figure 1. Typical Symmetric Key File 941@end example 942 943Figure 1 shows a typical symmetric keys file used by the reference 944implementation. 945Following the header the keys are entered one per line in the format 946@example 947@kbd{keyno} @kbd{type} @kbd{key} 948@end example 949where 950@kbd{keyno} 951is a positive integer in the range 1-65534; 952@kbd{type} 953is the key type for the message digest algorithm, which in the absence of the 954OpenSSL library must be 955@code{MD5} 956to designate the MD5 message digest algorithm; 957if the OpenSSL library is installed, the key type can be any 958message digest algorithm supported by that library; 959however, if compatibility with FIPS 140-2 is required, 960the key type must be either 961@code{SHA} 962or 963@code{SHA1}; 964@kbd{key} 965is the key itself, 966which is a printable ASCII string 20 characters or less in length: 967each character is chosen from the 93 printable characters 968in the range 0x21 through 0x7e ( 969@quoteleft{}@quoteright{}! 970through 971@quoteleft{}~@quoteright{} 972) excluding space and the 973@quoteleft{}#@quoteright{} 974character, and terminated by whitespace or a 975@quoteleft{}#@quoteright{} 976character. 977An OpenSSL key consists of a hex-encoded ASCII string of 40 characters, which 978is truncated as necessary. 979 980Note that the keys used by the 981@code{ntpq(1ntpqmdoc)} 982and 983@code{ntpdc(1ntpdcmdoc)} 984programs 985are checked against passwords requested by the programs 986and entered by hand, so it is generally appropriate to specify these keys 987in human readable ASCII format. 988 989The 990@code{ntp-keygen} 991program generates a symmetric keys file 992@file{ntpkey_MD5key_}@kbd{hostname}. @kbd{filestamp}. 993Since the file contains private shared keys, 994it should be visible only to root and distributed by secure means 995to other subnet hosts. 996The NTP daemon loads the file 997@file{ntp.keys}, 998so 999@code{ntp-keygen} 1000installs a soft link from this name to the generated file. 1001Subsequently, similar soft links must be installed by manual 1002or automated means on the other subnet hosts. 1003While this file is not used with the Autokey Version 2 protocol, 1004it is needed to authenticate some remote configuration commands 1005used by the 1006@code{ntpq(1ntpqmdoc)} 1007and 1008@code{ntpdc(1ntpdcmdoc)} 1009utilities. 1010 1011This section was generated by @strong{AutoGen}, 1012using the @code{agtexi-cmd} template and the option descriptions for the @code{ntp-keygen} program. 1013This software is released under the NTP license, <http://ntp.org/license>. 1014 1015@menu 1016* ntp-keygen usage:: ntp-keygen help/usage (@option{--help}) 1017* ntp-keygen imbits:: imbits option (-b) 1018* ntp-keygen certificate:: certificate option (-c) 1019* ntp-keygen cipher:: cipher option (-C) 1020* ntp-keygen id-key:: id-key option (-e) 1021* ntp-keygen gq-params:: gq-params option (-G) 1022* ntp-keygen host-key:: host-key option (-H) 1023* ntp-keygen iffkey:: iffkey option (-I) 1024* ntp-keygen ident:: ident option (-i) 1025* ntp-keygen lifetime:: lifetime option (-l) 1026* ntp-keygen modulus:: modulus option (-m) 1027* ntp-keygen md5key:: md5key option (-M) 1028* ntp-keygen pvt-cert:: pvt-cert option (-P) 1029* ntp-keygen password:: password option (-p) 1030* ntp-keygen export-passwd:: export-passwd option (-q) 1031* ntp-keygen subject-name:: subject-name option (-s) 1032* ntp-keygen sign-key:: sign-key option (-S) 1033* ntp-keygen trusted-cert:: trusted-cert option (-T) 1034* ntp-keygen mv-params:: mv-params option (-V) 1035* ntp-keygen mv-keys:: mv-keys option (-v) 1036* ntp-keygen config:: presetting/configuring ntp-keygen 1037* ntp-keygen exit status:: exit status 1038* ntp-keygen Usage:: Usage 1039* ntp-keygen Notes:: Notes 1040* ntp-keygen Bugs:: Bugs 1041@end menu 1042 1043@node ntp-keygen usage 1044@subsection ntp-keygen help/usage (@option{--help}) 1045@cindex ntp-keygen help 1046 1047This is the automatically generated usage text for ntp-keygen. 1048 1049The text printed is the same whether selected with the @code{help} option 1050(@option{--help}) or the @code{more-help} option (@option{--more-help}). @code{more-help} will print 1051the usage text by passing it through a pager program. 1052@code{more-help} is disabled on platforms without a working 1053@code{fork(2)} function. The @code{PAGER} environment variable is 1054used to select the program, defaulting to @file{more}. Both will exit 1055with a status code of 0. 1056 1057@exampleindent 0 1058@example 1059ntp-keygen (ntp) - Create a NTP host key - Ver. 4.2.7p245 1060USAGE: ntp-keygen [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... 1061 Flg Arg Option-Name Description 1062 -c Str certificate certificate scheme 1063 -C Str cipher privatekey cipher 1064 -d no debug-level Increase debug verbosity level 1065 - may appear multiple times 1066 -D Str set-debug-level Set the debug verbosity level 1067 - may appear multiple times 1068 -e no id-key Write IFF or GQ identity keys 1069 -G no gq-params Generate GQ parameters and keys 1070 -H no host-key generate RSA host key 1071 -I no iffkey generate IFF parameters 1072 -i Str ident set Autokey group name 1073 -l Num lifetime set certificate lifetime 1074 -M no md5key generate MD5 keys 1075 -m Num modulus modulus 1076 - It must be in the range: 1077 256 to 2048 1078 -P no pvt-cert generate PC private certificate 1079 -p Str pvt-passwd output private password 1080 -q Str get-pvt-passwd input private password 1081 -S Str sign-key generate sign key (RSA or DSA) 1082 -s Str subject-name set host and optionally group name 1083 -T no trusted-cert trusted certificate (TC scheme) 1084 -V Num mv-params generate <num> MV parameters 1085 -v Num mv-keys update <num> MV keys 1086 opt version Output version information and exit 1087 -? no help Display extended usage information and exit 1088 -! no more-help Extended usage information passed thru pager 1089 -> opt save-opts Save the option state to a config file 1090 -< Str load-opts Load options from a config file 1091 - disabled as --no-load-opts 1092 - may appear multiple times 1093 1094Options are specified by doubled hyphens and their name or by a single 1095hyphen and the flag character. 1096 1097 1098 1099The following option preset mechanisms are supported: 1100 - reading file $HOME/.ntprc 1101 - reading file ./.ntprc 1102 - examining environment variables named NTP_KEYGEN_* 1103 1104please send bug reports to: http://bugs.ntp.org, bugs@@ntp.org 1105@end example 1106@exampleindent 4 1107 1108@node ntp-keygen imbits 1109@subsection imbits option (-b) 1110@cindex ntp-keygen-imbits 1111 1112This is the ``identity modulus bits'' option. 1113This option takes a number argument @file{imbits}. 1114 1115@noindent 1116This option has some usage constraints. It: 1117@itemize @bullet 1118@item 1119must be compiled in by defining @code{AUTOKEY} during the compilation. 1120@end itemize 1121 1122The number of bits in the identity modulus. The default is 256. 1123@node ntp-keygen certificate 1124@subsection certificate option (-c) 1125@cindex ntp-keygen-certificate 1126 1127This is the ``certificate scheme'' option. 1128This option takes a string argument @file{scheme}. 1129 1130@noindent 1131This option has some usage constraints. It: 1132@itemize @bullet 1133@item 1134must be compiled in by defining @code{AUTOKEY} during the compilation. 1135@end itemize 1136 1137scheme is one of 1138RSA-MD2, RSA-MD5, RSA-MDC2, RSA-SHA, RSA-SHA1, RSA-RIPEMD160, 1139DSA-SHA, or DSA-SHA1. 1140 1141Select the certificate signature encryption/message digest scheme. 1142Note that RSA schemes must be used with a RSA sign key and DSA 1143schemes must be used with a DSA sign key. The default without 1144this option is RSA-MD5. 1145@node ntp-keygen cipher 1146@subsection cipher option (-C) 1147@cindex ntp-keygen-cipher 1148 1149This is the ``privatekey cipher'' option. 1150This option takes a string argument @file{cipher}. 1151 1152@noindent 1153This option has some usage constraints. It: 1154@itemize @bullet 1155@item 1156must be compiled in by defining @code{AUTOKEY} during the compilation. 1157@end itemize 1158 1159Select the cipher which is used to encrypt the files containing 1160private keys. The default is three-key triple DES in CBC mode, 1161equivalent to "@code{-C des-ede3-cbc}". The openssl tool lists ciphers 1162available in "@code{openssl -h}" output. 1163@node ntp-keygen id-key 1164@subsection id-key option (-e) 1165@cindex ntp-keygen-id-key 1166 1167This is the ``write iff or gq identity keys'' option. 1168 1169@noindent 1170This option has some usage constraints. It: 1171@itemize @bullet 1172@item 1173must be compiled in by defining @code{AUTOKEY} during the compilation. 1174@end itemize 1175 1176Write the public parameters from the IFF or GQ client keys to 1177the standard output. 1178This is intended for automatic key distribution by email. 1179@node ntp-keygen gq-params 1180@subsection gq-params option (-G) 1181@cindex ntp-keygen-gq-params 1182 1183This is the ``generate gq parameters and keys'' option. 1184 1185@noindent 1186This option has some usage constraints. It: 1187@itemize @bullet 1188@item 1189must be compiled in by defining @code{AUTOKEY} during the compilation. 1190@end itemize 1191 1192Generate parameters and keys for the GQ identification scheme, 1193obsoleting any that may exist. 1194@node ntp-keygen host-key 1195@subsection host-key option (-H) 1196@cindex ntp-keygen-host-key 1197 1198This is the ``generate rsa host key'' option. 1199 1200@noindent 1201This option has some usage constraints. It: 1202@itemize @bullet 1203@item 1204must be compiled in by defining @code{AUTOKEY} during the compilation. 1205@end itemize 1206 1207Generate new host keys, obsoleting any that may exist. 1208@node ntp-keygen iffkey 1209@subsection iffkey option (-I) 1210@cindex ntp-keygen-iffkey 1211 1212This is the ``generate iff parameters'' option. 1213 1214@noindent 1215This option has some usage constraints. It: 1216@itemize @bullet 1217@item 1218must be compiled in by defining @code{AUTOKEY} during the compilation. 1219@end itemize 1220 1221Generate parameters for the IFF identification scheme, obsoleting 1222any that may exist. 1223@node ntp-keygen ident 1224@subsection ident option (-i) 1225@cindex ntp-keygen-ident 1226 1227This is the ``set autokey group name'' option. 1228This option takes a string argument @file{group}. 1229 1230@noindent 1231This option has some usage constraints. It: 1232@itemize @bullet 1233@item 1234must be compiled in by defining @code{AUTOKEY} during the compilation. 1235@end itemize 1236 1237Set the optional Autokey group name to name. This is used in 1238the file name of IFF, GQ, and MV client parameters files. In 1239that role, the default is the host name if this option is not 1240provided. The group name, if specified using @code{-i/--ident} or 1241using @code{-s/--subject-name} following an '@code{@@}' character, 1242is also a part of the self-signed host certificate subject and 1243issuer names in the form @code{host@@group} and should match the 1244'@code{crypto ident}' or '@code{server ident}' configuration in the 1245@code{ntpd} configuration file. 1246@node ntp-keygen lifetime 1247@subsection lifetime option (-l) 1248@cindex ntp-keygen-lifetime 1249 1250This is the ``set certificate lifetime'' option. 1251This option takes a number argument @file{lifetime}. 1252 1253@noindent 1254This option has some usage constraints. It: 1255@itemize @bullet 1256@item 1257must be compiled in by defining @code{AUTOKEY} during the compilation. 1258@end itemize 1259 1260Set the certificate expiration to lifetime days from now. 1261@node ntp-keygen modulus 1262@subsection modulus option (-m) 1263@cindex ntp-keygen-modulus 1264 1265This is the ``prime modulus'' option. 1266This option takes a number argument @file{modulus}. 1267 1268@noindent 1269This option has some usage constraints. It: 1270@itemize @bullet 1271@item 1272must be compiled in by defining @code{AUTOKEY} during the compilation. 1273@end itemize 1274 1275The number of bits in the prime modulus. The default is 512. 1276@node ntp-keygen md5key 1277@subsection md5key option (-M) 1278@cindex ntp-keygen-md5key 1279 1280This is the ``generate symmetric keys'' option. 1281Generate symmetric keys, obsoleting any that may exist. 1282@node ntp-keygen pvt-cert 1283@subsection pvt-cert option (-P) 1284@cindex ntp-keygen-pvt-cert 1285 1286This is the ``generate pc private certificate'' option. 1287 1288@noindent 1289This option has some usage constraints. It: 1290@itemize @bullet 1291@item 1292must be compiled in by defining @code{AUTOKEY} during the compilation. 1293@end itemize 1294 1295Generate a private certificate. By default, the program generates 1296public certificates. 1297@node ntp-keygen password 1298@subsection password option (-p) 1299@cindex ntp-keygen-password 1300 1301This is the ``local private password'' option. 1302This option takes a string argument @file{passwd}. 1303 1304@noindent 1305This option has some usage constraints. It: 1306@itemize @bullet 1307@item 1308must be compiled in by defining @code{AUTOKEY} during the compilation. 1309@end itemize 1310 1311Local files containing private data are encrypted with the 1312DES-CBC algorithm and the specified password. The same password 1313must be specified to the local ntpd via the "crypto pw password" 1314configuration command. The default password is the local 1315hostname. 1316@node ntp-keygen export-passwd 1317@subsection export-passwd option (-q) 1318@cindex ntp-keygen-export-passwd 1319 1320This is the ``export iff or gq group keys with password'' option. 1321This option takes a string argument @file{passwd}. 1322 1323@noindent 1324This option has some usage constraints. It: 1325@itemize @bullet 1326@item 1327must be compiled in by defining @code{AUTOKEY} during the compilation. 1328@end itemize 1329 1330Export IFF or GQ identity group keys to the standard output, 1331encrypted with the DES-CBC algorithm and the specified password. 1332The same password must be specified to the remote ntpd via the 1333"crypto pw password" configuration command. See also the option 1334--id-key (-e) for unencrypted exports. 1335@node ntp-keygen subject-name 1336@subsection subject-name option (-s) 1337@cindex ntp-keygen-subject-name 1338 1339This is the ``set host and optionally group name'' option. 1340This option takes a string argument @file{host@@group}. 1341 1342@noindent 1343This option has some usage constraints. It: 1344@itemize @bullet 1345@item 1346must be compiled in by defining @code{AUTOKEY} during the compilation. 1347@end itemize 1348 1349Set the Autokey host name, and optionally, group name specified 1350following an '@code{@@}' character. The host name is used in the file 1351name of generated host and signing certificates, without the 1352group name. The host name, and if provided, group name are used 1353in @code{host@@group} form for the host certificate subject and issuer 1354fields. Specifying '@code{-s @@group}' is allowed, and results in 1355leaving the host name unchanged while appending @code{@@group} to the 1356subject and issuer fields, as with @code{-i group}. The group name, or 1357if not provided, the host name are also used in the file names 1358of IFF, GQ, and MV client parameter files. 1359@node ntp-keygen sign-key 1360@subsection sign-key option (-S) 1361@cindex ntp-keygen-sign-key 1362 1363This is the ``generate sign key (rsa or dsa)'' option. 1364This option takes a string argument @file{sign}. 1365 1366@noindent 1367This option has some usage constraints. It: 1368@itemize @bullet 1369@item 1370must be compiled in by defining @code{AUTOKEY} during the compilation. 1371@end itemize 1372 1373Generate a new sign key of the designated type, obsoleting any 1374that may exist. By default, the program uses the host key as the 1375sign key. 1376@node ntp-keygen trusted-cert 1377@subsection trusted-cert option (-T) 1378@cindex ntp-keygen-trusted-cert 1379 1380This is the ``trusted certificate (tc scheme)'' option. 1381 1382@noindent 1383This option has some usage constraints. It: 1384@itemize @bullet 1385@item 1386must be compiled in by defining @code{AUTOKEY} during the compilation. 1387@end itemize 1388 1389Generate a trusted certificate. By default, the program generates 1390a non-trusted certificate. 1391@node ntp-keygen mv-params 1392@subsection mv-params option (-V) 1393@cindex ntp-keygen-mv-params 1394 1395This is the ``generate <num> mv parameters'' option. 1396This option takes a number argument @file{num}. 1397 1398@noindent 1399This option has some usage constraints. It: 1400@itemize @bullet 1401@item 1402must be compiled in by defining @code{AUTOKEY} during the compilation. 1403@end itemize 1404 1405Generate parameters and keys for the Mu-Varadharajan (MV) 1406identification scheme. 1407@node ntp-keygen mv-keys 1408@subsection mv-keys option (-v) 1409@cindex ntp-keygen-mv-keys 1410 1411This is the ``update <num> mv keys'' option. 1412This option takes a number argument @file{num}. 1413 1414@noindent 1415This option has some usage constraints. It: 1416@itemize @bullet 1417@item 1418must be compiled in by defining @code{AUTOKEY} during the compilation. 1419@end itemize 1420 1421This option has no @samp{doc} documentation. 1422 1423 1424@node ntp-keygen config 1425@subsection presetting/configuring ntp-keygen 1426 1427Any option that is not marked as @i{not presettable} may be preset by 1428loading values from configuration ("rc" or "ini") files, and values from environment variables named @code{NTP-KEYGEN} and @code{NTP-KEYGEN_<OPTION_NAME>}. @code{<OPTION_NAME>} must be one of 1429the options listed above in upper case and segmented with underscores. 1430The @code{NTP-KEYGEN} variable will be tokenized and parsed like 1431the command line. The remaining variables are tested for existence and their 1432values are treated like option arguments. 1433 1434 1435@noindent 1436@code{libopts} will search in 2 places for configuration files: 1437@itemize @bullet 1438@item 1439$HOME 1440@item 1441$PWD 1442@end itemize 1443The environment variables @code{HOME}, and @code{PWD} 1444are expanded and replaced when @file{ntp-keygen} runs. 1445For any of these that are plain files, they are simply processed. 1446For any that are directories, then a file named @file{.ntprc} is searched for 1447within that directory and processed. 1448 1449Configuration files may be in a wide variety of formats. 1450The basic format is an option name followed by a value (argument) on the 1451same line. Values may be separated from the option name with a colon, 1452equal sign or simply white space. Values may be continued across multiple 1453lines by escaping the newline with a backslash. 1454 1455Multiple programs may also share the same initialization file. 1456Common options are collected at the top, followed by program specific 1457segments. The segments are separated by lines like: 1458@example 1459[NTP-KEYGEN] 1460@end example 1461@noindent 1462or by 1463@example 1464<?program ntp-keygen> 1465@end example 1466@noindent 1467Do not mix these styles within one configuration file. 1468 1469Compound values and carefully constructed string values may also be 1470specified using XML syntax: 1471@example 1472<option-name> 1473 <sub-opt>...<...>...</sub-opt> 1474</option-name> 1475@end example 1476@noindent 1477yielding an @code{option-name.sub-opt} string value of 1478@example 1479"...<...>..." 1480@end example 1481@code{AutoOpts} does not track suboptions. You simply note that it is a 1482hierarchicly valued option. @code{AutoOpts} does provide a means for searching 1483the associated name/value pair list (see: optionFindValue). 1484 1485The command line options relating to configuration and/or usage help are: 1486 1487@subsubheading version (-) 1488 1489Print the program version to standard out, optionally with licensing 1490information, then exit 0. The optional argument specifies how much licensing 1491detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 1492Only the first letter of the argument is examined: 1493 1494@table @samp 1495@item version 1496Only print the version. This is the default. 1497@item copyright 1498Name the copyright usage licensing terms. 1499@item verbose 1500Print the full copyright usage licensing terms. 1501@end table 1502 1503@node ntp-keygen exit status 1504@subsection ntp-keygen exit status 1505 1506One of the following exit values will be returned: 1507@table @samp 1508@item 0 (EXIT_SUCCESS) 1509Successful program execution. 1510@item 1 (EXIT_FAILURE) 1511The operation failed or the command syntax was not valid. 1512@item 66 (EX_NOINPUT) 1513A specified configuration file could not be loaded. 1514@item 70 (EX_SOFTWARE) 1515libopts had an internal operational error. Please report 1516it to autogen-users@@lists.sourceforge.net. Thank you. 1517@end table 1518@node ntp-keygen Usage 1519@subsection ntp-keygen Usage 1520@node ntp-keygen Notes 1521@subsection ntp-keygen Notes 1522@node ntp-keygen Bugs 1523@subsection ntp-keygen Bugs 1524