Rev 4925: (mbp) merge nmb's admin guide improvements in file:///home/pqm/archives/thelove/bzr/%2Btrunk/

Canonical.com Patch Queue Manager pqm at pqm.ubuntu.com
Thu Dec 24 06:55:38 GMT 2009


At file:///home/pqm/archives/thelove/bzr/%2Btrunk/

------------------------------------------------------------
revno: 4925 [merge]
revision-id: pqm at pqm.ubuntu.com-20091224065537-cngpc3v4qurvid04
parent: pqm at pqm.ubuntu.com-20091223075716-s7yaqku6wb4yh7ve
parent: mbp at sourcefrog.net-20091224060621-08t4n8jz048wxzfz
committer: Canonical.com Patch Queue Manager <pqm at pqm.ubuntu.com>
branch nick: +trunk
timestamp: Thu 2009-12-24 06:55:37 +0000
message:
  (mbp) merge nmb's admin guide improvements
modified:
  NEWS                           NEWS-20050323055033-4e00b5db738777ff
  doc/en/admin-guide/advanced.txt advanced.txt-20091205144603-lgpl0e0z6lzk2rdw-1
  doc/en/admin-guide/security.txt security.txt-20091205144603-lgpl0e0z6lzk2rdw-10
=== modified file 'NEWS'
--- a/NEWS	2009-12-23 05:52:00 +0000
+++ b/NEWS	2009-12-24 06:06:21 +0000
@@ -51,6 +51,10 @@
 Documentation
 *************
 
+* There is a System Administrator's Guide in ``doc/en/admin-guide``,
+  including discussions of installation, relevant plugins, security and 
+  backup.
+
 API Changes
 ***********
 

=== modified file 'doc/en/admin-guide/advanced.txt'
--- a/doc/en/admin-guide/advanced.txt	2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/advanced.txt	2009-12-22 05:22:53 +0000
@@ -12,3 +12,153 @@
 
 Multi-site Setups
 -----------------
+
+The "distributed" in distributed version control system should indicate that
+Bazaar is  well suited for multi-site development situations and indeed, that
+is the case.  The advantage comes from the ease and transparency of managing
+merges between branches with divergent history.  Note that there are many,
+many different ways to manage widely-flung development setups using Bazaar and
+its branching and merging capabilities.  These can be discovered and tested
+before being implemented as policy.  We will describe one such possible setup
+here.
+
+Consider ProjectX Corp's international expansion with a new branch office in
+Darwin, Australia, in addition to the company's headquarters in Austin, Texas,
+USA.  One of the difficulties of a far-flung multi-site development
+environment such as this is that the network connection between Australia and
+Texas is slow and unreliable.  So, each branch office would like the master
+branch to be local to them.  (In situations with good network connectivity, a
+local branch bound to the remote master may be all that is needed to support
+multi-site development.)
+
+Of course, with two master branches, there is always the question of which one
+is authoritative.  Given Bazaar's facility at managing multiple branches, we
+suggest that it is best not to privilege either the Texas or Australia
+branches, but to merge both of them into a separate master branch (which may
+reside at either site).  For definiteness, we will locate the master branch at
+the Texas site.  So, we will have three branches stored on two servers:
+trunk and texas-integration at the Texas site and australia-integration at the
+Darwin site.  These branches are named in terms of the sites where the 
+development takes place, but in many cases it may make more sense to name
+branches after the functional teams rather their geographical locations.
+Since we are trying illustrate the issues with multi-*site* development, we
+will persist in this naming scheme.
+
+Setup
+~~~~~
+
+Using our previous setup at the Texas site, we will simply rename the old
+trunk branch as trunk and branch a copy as texas-integration.
+
+::
+ 
+  $ cd /srv/bzr/projectx
+  $ mv trunk trunk              # can simply rename on the filesystem
+  $ bzr branch trunk texas-integration   # very fast in a shared repository
+
+In Australia, we need to set up the ``/srv/bzr/projectx`` directory and get a
+copy of the current trunk as australia-integration::
+
+  $ mkdir -p /srv/bzr
+  $ cd /srv/bzr
+  $ bzr init-repo --no-trees projectx
+  $ cd projectx
+  $ bzr branch bzr+ssh://server.example.com/srv/bzr/trunk
+  $ bzr branch trunk australia-integration
+
+Merging to master
+~~~~~~~~~~~~~~~~~
+
+Then, each office works with their local copy of the trunk.  At some point,
+sooner or later depending on the pace of development in the two locations, the
+two local trunks need to be merged.  (In general, sooner beats later when
+merging, since there is no penalty for multiple merges.)  In this example,
+Alice at the Texas office will do the merging on her local machine using
+branches on the server::
+
+  # Get a copy of the Australia branch in Texas.  After the initial branch
+  # command, use pull to keep the branch up to date.  With a slow network,
+  # this is the only slow part
+  $ bzr branch bzr+ssh://autralia.example.com/srv/bzr/projectx/australia-integration \
+    bzr+ssh://server.example.com/srv/bzr/projectx/australia-integration
+  
+  # Check out the master branch locally for doing the merge
+  $ cd ~/projectx
+  $ bzr checkout bzr+ssh://server.example.com/srv/bzr/projectx/trunk
+  $ cd trunk
+  $ bzr merge bzr+ssh://server.example.com/srv/bzr/projectx/texas-integration
+  # Run the test suite and resolve any conflicts
+  $ bzr commit -m "Merge Texas branch to master"
+  
+  # Now, merge from Australia using the local copy of that branch
+  $ bzr merge bzr+ssh://server.example.com/srv/bzr/projectx/australia-integration
+  # Run the test suite and resolve any conflicts between the two offices
+  $ bzr commit -m "Merge Australia branch to master"
+
+Note that Bazaar does not commit even cleanly applied merges by default.  This
+is because although a merge may apply cleanly, the merged state still needs to
+be checked before it is committed.  (Just because there are no text conflicts
+does not mean that everything will work after a merge.)  An alternative that 
+can pull when possible and merge otherwise is available with 
+``bzr merge --pull``.
+
+Merging back to local trunks
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now the trunk branch is the most up-to-date version of the software and
+both of the local trunks need to reincorporate the changes from the master.
+If no new commits have been made to texas-integration, then that can happen using
+``bzr pull``::
+
+  $ cd ~/projectx
+  $ bzr checkout bzr+ssh://server.example.com/srv/bzr/projectx/texas-integration
+  $ cd texas-integration
+  $ bzr pull ../trunk  # Use trunk from the local disk
+                              # No need to commit
+
+If new changes have happened on texas-integration since the integration with
+trunk, then the above pull will produce an error suggesting to use
+merge::
+
+  $ bzr merge ../trunk
+  # Run test suite, resolve conflicts
+  $ bzr commit -m "Merging Australian changes"
+
+In Australia, they will need to update their local copy of trunk::
+
+  $ cd /srv/bzr/projectx/trunk
+  $ bzr pull     # parent location is used by default
+
+Then, they need to pull or merge the changes from trunk into the local trunk.
+This should be done by a developer with a checkout of australia-integration so
+that they can run the test suite::
+
+  $ cd ~/projectx
+  $ bzr co bzr+ssh://australia.example.com/srv/bzr/projectx/australia-integration
+  $ cd australia-integration
+  $ bzr merge bzr+ssh://australia.example.com/srv/bzr/projectx/trunk
+  # Run test suite and integrate Texan changes with only recent local
+  # development
+  $ bzr commit -m "Integrate work from Texas"
+
+
+Other Considerations
+~~~~~~~~~~~~~~~~~~~~
+
+Multi-site deployments can be complicated, due to the many possible variations
+of development velocity, divisions of labor, network connectivity, resources
+for integration, etc.  The preceding description is meant to be one possible
+way to do fairly symmetric multi-site development.  (Neither Texas or
+Australia is privileged in this structure.)  In a situation where there is one
+main site and other smaller sites, one of the local trunk branches can be
+eliminated and trunk can be used directly for development at the main
+site.
+
+It is also up to the particular situation how frequently the local trunks are
+integrated into the master trunk.  Given resources specifically for
+integration, it is conceivable that a developer may be constantly responsible
+for integrating changes from the two teams.  Alternatively, the two sites
+could work on well-separated, well-defined features and merge to the master
+trunk only when their respective features are complete.  Given the difficulty
+of resolving conflicts in very large merges and the ease of merge handling in
+Bazaar, we suggest that merges be done more frequently, rather than less.

=== modified file 'doc/en/admin-guide/security.txt'
--- a/doc/en/admin-guide/security.txt	2009-12-07 18:12:21 +0000
+++ b/doc/en/admin-guide/security.txt	2009-12-22 04:55:15 +0000
@@ -4,6 +4,113 @@
 Authentication
 --------------
 
+Bazaar's philosophy on authentication is that it is best to reuse existing
+authentication technologies, rather than trying to reinvent potentially
+complicated methods for securely identifying users.  As such, we describe two
+such uses of existing software for authentication purposes.
+
+Using SSH
+~~~~~~~~~
+
+SSH is a very well tested and featureful technology for authenticating users.
+For situations where all of the developers have local accounts on the server,
+it is trivial to provide secure, authenticated ``bzr+ssh://`` access.  One
+concern with this method is that it may not be desirable to grant shell access
+to developers on the server machine.  In this case, Bazaar provides
+``bzr_ssh_path_limiter``, a script that runs the Bazaar smart server on the
+server machine at a specified path, and allows no other access.
+
+To set it up, specify::
+
+   command="/path/to/bzr_ssh_path_limiter <path>" <typical key line>
+
+in each user's ``~/.ssh/authorized_keys`` file on the server, where `<path>` is
+the path to limit access to (and its subdirectories).  For more documentation
+on the syntax of the ``authorized_keys`` file see the documentation of the SSH
+server.  This will only permit Bazaar access to the specified path and no other
+SSH access for that user.
+
+If it isn't desired to give each user an account on the server, multiple
+private/public key pairs can be included under one single SSH account (say
+sshuser) in the ``~sshuser/.ssh/authorized_keys`` file and then each developer
+can be given their own private key.  They can then use
+``bzr+ssh://sshuser@server.example.com/`` URLs to access the server.
+
+Using HTTP authentication methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 Access Control
 --------------
 
+Many projects need fine-grained access control on who may read and write to
+which branches.  Incorporating these controls into OS-level user accounts
+using groups and filesystem permissions can be difficult or even not permitted
+in some instances.  Bazaar provides a script called ``bzr_access`` that can be
+used to provide access control based on usernames, with authentication
+performed by SSH.  To do so, we need to set up private-key authentication in
+SSH.  This can be done using a single SSH user on the server, or one account
+per user.  The idea is to use the SSH's ``authorized_keys`` file to specify
+the ``bzr_access`` script as the only command that can be run by a user
+identified by a particular key pair.
+
+First, you will need to generate a private/public key pair for each user who
+will be accessing the repository.  The private key should be distributed to
+the user and the public key will be needed on the server to identify the user.
+On the server, in the SSH user's ``~/.ssh/authorized_keys`` file, use the
+following line for each repository user and the corresponding public key::
+
+  command="/path/to/bzr_access /path/to/bzr /path/to/repository <username>",no- port-forwarding,no-X11-forwarding,no-agent-forwarding ssh-<type> <key>
+
+where `<key>` is the (possibly very long) public key, `<type>` is the type of
+SSH key and `<username>` is the username to associate with that public key.
+
+The ``bzr_access`` script obtains its configuration information from the file
+``/path/to/repository/bzr_access.conf``.  This file should not be placed under
+version control in a branch located at ``/path/to/repository`` since that
+would allow anyone with access to the repository to change the access control
+rules.  The ``bzr_access.conf`` file is in a simple INI-style format with
+sections defined by ``[groups]`` and ``[/]``.  The options in the ``[groups]``
+section are the names of groups and the values of those options should be the
+usernames in that group.  Inside the ``[/]`` section, the options are
+usernames or group names (prefixed with ``@``) and the values are either
+``rw``, ``r`` or nothing, representing read-write access, read-only access or
+no access at all.  A sample of ``bzr_access.conf`` could be::
+
+   [groups]
+   admins = alpha
+   devels = beta, gamma, delta
+   
+   [/]
+   @admins = rw
+   @devels = r
+   upsilon = 
+
+where the user whose key is associated with `alpha` would have read-write
+access, the users `beta`, `gamma` and `delta` would have read-only access and
+user `upsilon` would not be able to access any branches under
+``/path/to/repository``.
+
+Additional Considerations with ``bzr_access``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As currently written, ``bzr_access`` only allows each public key to be
+associated with a single repository location.  This means that if developers
+need to access two or more different repositories, then each developer will
+need to have two or more private keys for SSH and be able to select between
+them (see ``man ssh`` for more information on configuring multiple private
+keys).
+
+Also, each repository can only have a single configuration file, with access
+configured for all branches in the repository.  This means that if different
+access rules are needed for different projects, then those projects must be in
+different repositories.  This then necessitates the use of multiple private
+keys as just described.
+
+Finally, as noted above under `Using SSH`_ all of the public keys may be
+included in the ``authorized_keys`` file of a single user on the server.  It
+is also possible to use a single private/public key pair for all of the
+developers, but this only allows a single username for access control to the
+repository (since the username is associated with the public key in
+``authorized_keys``.  While this is certainly possible it seems to defeat the
+purpose of fine-grained access control, although it does provide the same
+limited SSH access as that described above.




More information about the bazaar-commits mailing list