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