Ignore:
Timestamp:
Apr 12, 2015, 8:57:05 PM (5 years ago)
Author:
cal@…
Message:

base: document pubkeys.conf

File:
1 copied

Legend:

Unmodified
Added
Removed
  • trunk/base/doc/pubkeys.conf.5.txt

    r134981 r134983  
    11// vim: set et sw=4 ts=8 ft=asciidoc tw=80:
    2 sources.conf(5)
     2pubkeys.conf(5)
    33===============
    44$Id$
     
    66NAME
    77----
    8 sources.conf - port definition configuration file of the MacPorts system
     8pubkeys.conf - public key configuration file of the MacPorts system
    99
    1010DESCRIPTION
    1111-----------
    12 *sources.conf* is the configuration file used by the MacPorts system to locate
    13 its port definitions. The file is read by the *port* command to find available
    14 ports and how to install them. Lines beginning with '#' are comments, empty
    15 lines are ignored. Entries in this file are URIs optionally followed by flags in
    16 square brackets. Each source specification is given on a separate line.
    17 A grammar in EBNF is given below:
    18 --------
    19 line  = URI, [ '[', flag, { space, flag }, ']' ] ;
    20 flag  = 'default' | 'nosync' ;
    21 space = ' ' | '\t' ;
    22 --------
     12*pubkeys.conf* is the configuration file used by the MacPorts system to locate
     13the public keys used to verify the integrity and authenticity of
    2314
    24 URI FORMATS
    25 -----------
    26 // Set default style for second-level labeled lists in this section
    27 //:listdef-labeled2.style: horizontal
     15- the tree of port definitions,
     16- downloaded pre-built binary archives, and
     17- MacPorts updates.
    2818
    29 MacPorts supports a number of different protocols as source descriptions.
     19The file is read by the *port* command. Lines beginning with '#' are comments,
     20empty lines are ignored. All other lines must contain absolute paths of
     21PEM-encoded RSA public keys for use by OpenSSL.
    3022
    31 'rsync://'::
    32     Followed by a server name and a path on this server, this URI instructs
    33     MacPorts to fetch the contents of the file or directory referenced by this
    34     URI into a path of its own choosing. This is the default method of port tree
    35     synchronization and is generally recommended. MacPorts will derive
    36     a machine- and architecture-specific URI (in the subdirectory
    37     PortIndex_$\{platform\}_$\{os_major\}_$\{os_arch\}/) and attempt to download
    38     a pre-generated PortIndex (including the PortIndex.quick file) from there.
    39     +
    40     *Example*;;
    41         rsync://rsync.macports.org/release/tarballs/ports.tar
    42     *Default*;;
    43         rsync://rsync.macports.org/release/tarballs/ports.tar [default]
    44 
    45 'file://'::
    46     Followed by an absolute path (which will result in *three* slashes at the
    47     beginning of the URI) to a local directory that should be used as port tree.
    48     A port index will automatically be generated for this source. Note that
    49     MacPorts will try to determine whether the given path is under source
    50     control and attempt to update from the default remote server if it is.
    51     Currently, Subversion and Git (including git-svn) are supported options. You
    52     can add the 'nosync' tag to avoid this behavior.
    53     +
    54     NOTE: The MacPorts user (usually called 'macports') needs to be able to read
    55     and write to this location. This usually means your home directory is not
    56     a suitable place for a port tree, unless you adjust permissions accordingly.
    57     +
    58     *Example*;;
    59         file:///opt/dports [nosync,default]
    60     *Default*;;
    61         none
    62 
    63 'http://', 'https://' and 'ftp://'::
    64     Followed by a server name and a path on this server, this URI instructs
    65     MacPorts to download a tarball snapshot of a ports tree from the URI and
    66     extract it to a path of its choice. This possibility is provided as
    67     a fallback to users that can use neither rsync nor subversion to sync the
    68     MacPorts port tree.
    69     +
    70     If the tarball contains a pre-built PortIndex and PortIndex.quick file at
    71     PortIndex_$\{platform\}_$\{os_major\}_$\{os_arch\}/, those will be used as
    72     default. If it does not, MacPorts will build a suitable port index for the
    73     local system automatically.
    74 
    75 SOURCE FORMATS
    76 --------------
    77 Port definition trees can be either directories (e.g. for the 'file://' and
    78 rsync methods) or tarballs (for HTTP, HTTPS, FTP and rsync). For the directory
    79 format, no additional verification is performed. Because transfers using rsync
    80 are not encrypted or authenticated, the use of this setup over rsync is
    81 discouraged.
    82 
    83 If the URI ends with '.tar', MacPorts assumes the source is a tarball and
    84 attempts to download an additional '.tar.rmd160' signature file. It then uses
    85 the public keys configured in man:pubkeys.conf[5] to verify this signature to
    86 ensure the source has not been tampered with. You are strongly encouraged to use
    87 this setup, and it has been the default for MacPorts since it has been
    88 introduced.
    89 
    90 FLAGS
    91 -----
    92 Source specifications support a number of flags that modify the behavior of
    93 a source:
    94 
    95 'nosync'::
    96     Skip this source when *port sync* or *port selfupdate* are used. You can use
    97     this flag to avoid updating your local ports tree managed by a source
    98     control system such as Git or Subversion. You are responsible for generating
    99     a current port index using the man:portindex[1] command for sources marked
    100     with this flag.
    101 
    102 'default'::
    103     Mark this source as the default. The default source is used as a fallback to
    104     load additional files (such as PortGroups and mirror definitions) from the
    105     '_resources/port1.0' directory.
     23MacPorts comes pre-configured with its official public key. The authenticity of
     24the public key file is provided by the MacPorts installer, which is
     25cryptographically signed with an Apple Developer ID of one of the MacPorts
     26developers. Unless you want to provide your own separate ports tree or your own
     27pre-built binary archives, there is no need to modify the *pubkeys.conf* file.
    10628
    10729FILES
    10830-----
    109 The path of the 'sources.conf' file is specified in the *sources_conf* option of
    110 man:macports.conf[5]. It defaults to '$\{prefix\}/etc/macports/sources.conf'.
    111 There is no user-specific 'sources.conf' file, but support for this can be
    112 emulated by setting 'sources.conf' in the user-specific man:macports.conf[5]
    113 file.
     31$\{prefix\}/etc/macports/pubkeys.conf::
     32    Standard system-wide MacPorts public key configuration file.
     33
     34User-specific configuration of public keys is not supported.
    11435
    11536SEE ALSO
    11637--------
    117 man:port[1], man:port-selfupdate[1], man:port-sync[1], man:portindex[1],
    118 man:macports.conf[5]
     38man:port[1], man:macports.conf[5]
    11939
    12040AUTHORS
Note: See TracChangeset for help on using the changeset viewer.