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 20, 2019 at 09:57:13 AM 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-65535; 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.8p13 1060Usage: ntp-keygen [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... 1061 Flg Arg Option-Name Description 1062 -b Num imbits identity modulus bits 1063 - it must be in the range: 1064 256 to 2048 1065 -c Str certificate certificate scheme 1066 -C Str cipher privatekey cipher 1067 -d no debug-level Increase debug verbosity level 1068 - may appear multiple times 1069 -D Num set-debug-level Set the debug verbosity level 1070 - may appear multiple times 1071 -e no id-key Write IFF or GQ identity keys 1072 -G no gq-params Generate GQ parameters and keys 1073 -H no host-key generate RSA host key 1074 -I no iffkey generate IFF parameters 1075 -i Str ident set Autokey group name 1076 -l Num lifetime set certificate lifetime 1077 -m Num modulus prime modulus 1078 - it must be in the range: 1079 256 to 2048 1080 -M no md5key generate symmetric keys 1081 -P no pvt-cert generate PC private certificate 1082 -p Str password local private password 1083 -q Str export-passwd export IFF or GQ group keys with password 1084 -s Str subject-name set host and optionally group name 1085 -S Str sign-key generate sign key (RSA or DSA) 1086 -T no trusted-cert trusted certificate (TC scheme) 1087 -V Num mv-params generate <num> MV parameters 1088 -v Num mv-keys update <num> MV keys 1089 opt version output version information and exit 1090 -? no help display extended usage information and exit 1091 -! no more-help extended usage information passed thru pager 1092 -> opt save-opts save the option state to a config file 1093 -< Str load-opts load options from a config file 1094 - disabled as '--no-load-opts' 1095 - may appear multiple times 1096 1097Options are specified by doubled hyphens and their name or by a single 1098hyphen and the flag character. 1099 1100 1101The following option preset mechanisms are supported: 1102 - reading file $HOME/.ntprc 1103 - reading file ./.ntprc 1104 - examining environment variables named NTP_KEYGEN_* 1105 1106Please send bug reports to: <http://bugs.ntp.org, bugs@@ntp.org> 1107@end example 1108@exampleindent 4 1109 1110@node ntp-keygen imbits 1111@subsection imbits option (-b) 1112@cindex ntp-keygen-imbits 1113 1114This is the ``identity modulus bits'' option. 1115This option takes a number argument @file{imbits}. 1116 1117@noindent 1118This option has some usage constraints. It: 1119@itemize @bullet 1120@item 1121must be compiled in by defining @code{AUTOKEY} during the compilation. 1122@end itemize 1123 1124The number of bits in the identity modulus. The default is 256. 1125@node ntp-keygen certificate 1126@subsection certificate option (-c) 1127@cindex ntp-keygen-certificate 1128 1129This is the ``certificate scheme'' option. 1130This option takes a string argument @file{scheme}. 1131 1132@noindent 1133This option has some usage constraints. It: 1134@itemize @bullet 1135@item 1136must be compiled in by defining @code{AUTOKEY} during the compilation. 1137@end itemize 1138 1139scheme is one of 1140RSA-MD2, RSA-MD5, RSA-MDC2, RSA-SHA, RSA-SHA1, RSA-RIPEMD160, 1141DSA-SHA, or DSA-SHA1. 1142 1143Select the certificate signature encryption/message digest scheme. 1144Note that RSA schemes must be used with a RSA sign key and DSA 1145schemes must be used with a DSA sign key. The default without 1146this option is RSA-MD5. 1147@node ntp-keygen cipher 1148@subsection cipher option (-C) 1149@cindex ntp-keygen-cipher 1150 1151This is the ``privatekey cipher'' option. 1152This option takes a string argument @file{cipher}. 1153 1154@noindent 1155This option has some usage constraints. It: 1156@itemize @bullet 1157@item 1158must be compiled in by defining @code{AUTOKEY} during the compilation. 1159@end itemize 1160 1161Select the cipher which is used to encrypt the files containing 1162private keys. The default is three-key triple DES in CBC mode, 1163equivalent to "@code{-C des-ede3-cbc}". The openssl tool lists ciphers 1164available in "@code{openssl -h}" output. 1165@node ntp-keygen id-key 1166@subsection id-key option (-e) 1167@cindex ntp-keygen-id-key 1168 1169This is the ``write iff or gq identity keys'' option. 1170 1171@noindent 1172This option has some usage constraints. It: 1173@itemize @bullet 1174@item 1175must be compiled in by defining @code{AUTOKEY} during the compilation. 1176@end itemize 1177 1178Write the public parameters from the IFF or GQ client keys to 1179the standard output. 1180This is intended for automatic key distribution by email. 1181@node ntp-keygen gq-params 1182@subsection gq-params option (-G) 1183@cindex ntp-keygen-gq-params 1184 1185This is the ``generate gq parameters and keys'' option. 1186 1187@noindent 1188This option has some usage constraints. It: 1189@itemize @bullet 1190@item 1191must be compiled in by defining @code{AUTOKEY} during the compilation. 1192@end itemize 1193 1194Generate parameters and keys for the GQ identification scheme, 1195obsoleting any that may exist. 1196@node ntp-keygen host-key 1197@subsection host-key option (-H) 1198@cindex ntp-keygen-host-key 1199 1200This is the ``generate rsa host key'' option. 1201 1202@noindent 1203This option has some usage constraints. It: 1204@itemize @bullet 1205@item 1206must be compiled in by defining @code{AUTOKEY} during the compilation. 1207@end itemize 1208 1209Generate new host keys, obsoleting any that may exist. 1210@node ntp-keygen iffkey 1211@subsection iffkey option (-I) 1212@cindex ntp-keygen-iffkey 1213 1214This is the ``generate iff parameters'' option. 1215 1216@noindent 1217This option has some usage constraints. It: 1218@itemize @bullet 1219@item 1220must be compiled in by defining @code{AUTOKEY} during the compilation. 1221@end itemize 1222 1223Generate parameters for the IFF identification scheme, obsoleting 1224any that may exist. 1225@node ntp-keygen ident 1226@subsection ident option (-i) 1227@cindex ntp-keygen-ident 1228 1229This is the ``set autokey group name'' option. 1230This option takes a string argument @file{group}. 1231 1232@noindent 1233This option has some usage constraints. It: 1234@itemize @bullet 1235@item 1236must be compiled in by defining @code{AUTOKEY} during the compilation. 1237@end itemize 1238 1239Set the optional Autokey group name to name. This is used in 1240the file name of IFF, GQ, and MV client parameters files. In 1241that role, the default is the host name if this option is not 1242provided. The group name, if specified using @code{-i/--ident} or 1243using @code{-s/--subject-name} following an '@code{@@}' character, 1244is also a part of the self-signed host certificate subject and 1245issuer names in the form @code{host@@group} and should match the 1246'@code{crypto ident}' or '@code{server ident}' configuration in the 1247@code{ntpd} configuration file. 1248@node ntp-keygen lifetime 1249@subsection lifetime option (-l) 1250@cindex ntp-keygen-lifetime 1251 1252This is the ``set certificate lifetime'' option. 1253This option takes a number argument @file{lifetime}. 1254 1255@noindent 1256This option has some usage constraints. It: 1257@itemize @bullet 1258@item 1259must be compiled in by defining @code{AUTOKEY} during the compilation. 1260@end itemize 1261 1262Set the certificate expiration to lifetime days from now. 1263@node ntp-keygen modulus 1264@subsection modulus option (-m) 1265@cindex ntp-keygen-modulus 1266 1267This is the ``prime modulus'' option. 1268This option takes a number argument @file{modulus}. 1269 1270@noindent 1271This option has some usage constraints. It: 1272@itemize @bullet 1273@item 1274must be compiled in by defining @code{AUTOKEY} during the compilation. 1275@end itemize 1276 1277The number of bits in the prime modulus. The default is 512. 1278@node ntp-keygen md5key 1279@subsection md5key option (-M) 1280@cindex ntp-keygen-md5key 1281 1282This is the ``generate symmetric keys'' option. 1283Generate symmetric keys, obsoleting any that may exist. 1284@node ntp-keygen pvt-cert 1285@subsection pvt-cert option (-P) 1286@cindex ntp-keygen-pvt-cert 1287 1288This is the ``generate pc private certificate'' option. 1289 1290@noindent 1291This option has some usage constraints. It: 1292@itemize @bullet 1293@item 1294must be compiled in by defining @code{AUTOKEY} during the compilation. 1295@end itemize 1296 1297Generate a private certificate. By default, the program generates 1298public certificates. 1299@node ntp-keygen password 1300@subsection password option (-p) 1301@cindex ntp-keygen-password 1302 1303This is the ``local private password'' option. 1304This option takes a string argument @file{passwd}. 1305 1306@noindent 1307This option has some usage constraints. It: 1308@itemize @bullet 1309@item 1310must be compiled in by defining @code{AUTOKEY} during the compilation. 1311@end itemize 1312 1313Local files containing private data are encrypted with the 1314DES-CBC algorithm and the specified password. The same password 1315must be specified to the local ntpd via the "crypto pw password" 1316configuration command. The default password is the local 1317hostname. 1318@node ntp-keygen export-passwd 1319@subsection export-passwd option (-q) 1320@cindex ntp-keygen-export-passwd 1321 1322This is the ``export iff or gq group keys with password'' option. 1323This option takes a string argument @file{passwd}. 1324 1325@noindent 1326This option has some usage constraints. It: 1327@itemize @bullet 1328@item 1329must be compiled in by defining @code{AUTOKEY} during the compilation. 1330@end itemize 1331 1332Export IFF or GQ identity group keys to the standard output, 1333encrypted with the DES-CBC algorithm and the specified password. 1334The same password must be specified to the remote ntpd via the 1335"crypto pw password" configuration command. See also the option 1336--id-key (-e) for unencrypted exports. 1337@node ntp-keygen subject-name 1338@subsection subject-name option (-s) 1339@cindex ntp-keygen-subject-name 1340 1341This is the ``set host and optionally group name'' option. 1342This option takes a string argument @file{host@@group}. 1343 1344@noindent 1345This option has some usage constraints. It: 1346@itemize @bullet 1347@item 1348must be compiled in by defining @code{AUTOKEY} during the compilation. 1349@end itemize 1350 1351Set the Autokey host name, and optionally, group name specified 1352following an '@code{@@}' character. The host name is used in the file 1353name of generated host and signing certificates, without the 1354group name. The host name, and if provided, group name are used 1355in @code{host@@group} form for the host certificate subject and issuer 1356fields. Specifying '@code{-s @@group}' is allowed, and results in 1357leaving the host name unchanged while appending @code{@@group} to the 1358subject and issuer fields, as with @code{-i group}. The group name, or 1359if not provided, the host name are also used in the file names 1360of IFF, GQ, and MV client parameter files. 1361@node ntp-keygen sign-key 1362@subsection sign-key option (-S) 1363@cindex ntp-keygen-sign-key 1364 1365This is the ``generate sign key (rsa or dsa)'' option. 1366This option takes a string argument @file{sign}. 1367 1368@noindent 1369This option has some usage constraints. It: 1370@itemize @bullet 1371@item 1372must be compiled in by defining @code{AUTOKEY} during the compilation. 1373@end itemize 1374 1375Generate a new sign key of the designated type, obsoleting any 1376that may exist. By default, the program uses the host key as the 1377sign key. 1378@node ntp-keygen trusted-cert 1379@subsection trusted-cert option (-T) 1380@cindex ntp-keygen-trusted-cert 1381 1382This is the ``trusted certificate (tc scheme)'' option. 1383 1384@noindent 1385This option has some usage constraints. It: 1386@itemize @bullet 1387@item 1388must be compiled in by defining @code{AUTOKEY} during the compilation. 1389@end itemize 1390 1391Generate a trusted certificate. By default, the program generates 1392a non-trusted certificate. 1393@node ntp-keygen mv-params 1394@subsection mv-params option (-V) 1395@cindex ntp-keygen-mv-params 1396 1397This is the ``generate <num> mv parameters'' option. 1398This option takes a number argument @file{num}. 1399 1400@noindent 1401This option has some usage constraints. It: 1402@itemize @bullet 1403@item 1404must be compiled in by defining @code{AUTOKEY} during the compilation. 1405@end itemize 1406 1407Generate parameters and keys for the Mu-Varadharajan (MV) 1408identification scheme. 1409@node ntp-keygen mv-keys 1410@subsection mv-keys option (-v) 1411@cindex ntp-keygen-mv-keys 1412 1413This is the ``update <num> mv keys'' option. 1414This option takes a number argument @file{num}. 1415 1416@noindent 1417This option has some usage constraints. It: 1418@itemize @bullet 1419@item 1420must be compiled in by defining @code{AUTOKEY} during the compilation. 1421@end itemize 1422 1423This option has no @samp{doc} documentation. 1424 1425 1426@node ntp-keygen config 1427@subsection presetting/configuring ntp-keygen 1428 1429Any option that is not marked as @i{not presettable} may be preset by 1430loading 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 1431the options listed above in upper case and segmented with underscores. 1432The @code{NTP-KEYGEN} variable will be tokenized and parsed like 1433the command line. The remaining variables are tested for existence and their 1434values are treated like option arguments. 1435 1436 1437@noindent 1438@code{libopts} will search in 2 places for configuration files: 1439@itemize @bullet 1440@item 1441$HOME 1442@item 1443$PWD 1444@end itemize 1445The environment variables @code{HOME}, and @code{PWD} 1446are expanded and replaced when @file{ntp-keygen} runs. 1447For any of these that are plain files, they are simply processed. 1448For any that are directories, then a file named @file{.ntprc} is searched for 1449within that directory and processed. 1450 1451Configuration files may be in a wide variety of formats. 1452The basic format is an option name followed by a value (argument) on the 1453same line. Values may be separated from the option name with a colon, 1454equal sign or simply white space. Values may be continued across multiple 1455lines by escaping the newline with a backslash. 1456 1457Multiple programs may also share the same initialization file. 1458Common options are collected at the top, followed by program specific 1459segments. The segments are separated by lines like: 1460@example 1461[NTP-KEYGEN] 1462@end example 1463@noindent 1464or by 1465@example 1466<?program ntp-keygen> 1467@end example 1468@noindent 1469Do not mix these styles within one configuration file. 1470 1471Compound values and carefully constructed string values may also be 1472specified using XML syntax: 1473@example 1474<option-name> 1475 <sub-opt>...<...>...</sub-opt> 1476</option-name> 1477@end example 1478@noindent 1479yielding an @code{option-name.sub-opt} string value of 1480@example 1481"...<...>..." 1482@end example 1483@code{AutoOpts} does not track suboptions. You simply note that it is a 1484hierarchicly valued option. @code{AutoOpts} does provide a means for searching 1485the associated name/value pair list (see: optionFindValue). 1486 1487The command line options relating to configuration and/or usage help are: 1488 1489@subsubheading version (-) 1490 1491Print the program version to standard out, optionally with licensing 1492information, then exit 0. The optional argument specifies how much licensing 1493detail to provide. The default is to print just the version. The licensing infomation may be selected with an option argument. 1494Only the first letter of the argument is examined: 1495 1496@table @samp 1497@item version 1498Only print the version. This is the default. 1499@item copyright 1500Name the copyright usage licensing terms. 1501@item verbose 1502Print the full copyright usage licensing terms. 1503@end table 1504 1505@node ntp-keygen exit status 1506@subsection ntp-keygen exit status 1507 1508One of the following exit values will be returned: 1509@table @samp 1510@item 0 (EXIT_SUCCESS) 1511Successful program execution. 1512@item 1 (EXIT_FAILURE) 1513The operation failed or the command syntax was not valid. 1514@item 66 (EX_NOINPUT) 1515A specified configuration file could not be loaded. 1516@item 70 (EX_SOFTWARE) 1517libopts had an internal operational error. Please report 1518it to autogen-users@@lists.sourceforge.net. Thank you. 1519@end table 1520@node ntp-keygen Usage 1521@subsection ntp-keygen Usage 1522@node ntp-keygen Notes 1523@subsection ntp-keygen Notes 1524@node ntp-keygen Bugs 1525@subsection ntp-keygen Bugs 1526