← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to doc/en/admin-guide/simple-setups.txt

Modify test_tsort_partial to accept multiple valid orderings.

This test previously checked for an exact match on the result of
tsort.topo_sort, while only a partial ordering is garantueed.  The current
implementation of topo_sort indeed returns the graph in lexicographical order,
but this depends on the order in which dict.popitem() pops and that is a
Python implementation detail not to be relied on.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/en/admin-guide/simple-setups.txt
1
 
Simple Setups
2
 
=============
3
 
 
4
 
Consider the following simple scenario where we will be serving Bazaar branches
5
 
that live on a single server.  Those branches are in the subdirectories of
6
 
``/srv/bzr`` (or ``C:\bzr``) and they will all be related to a single project
7
 
called "ProjectX".  ProjectX will have a trunk branch and at least one feature
8
 
branch.  As we get further, we will consider other scenarios, but this will be
9
 
a sufficiently motivating example.
10
 
 
11
 
Smart server
12
 
------------
13
 
 
14
 
The simplest possible setup for providing outside access to the branches on
15
 
the server uses Bazaar's built-in smart server tunneled over SSH_ so
16
 
that people who can access your server using SSH can have read and write
17
 
access to branches on the server.  This setup uses the authentication
18
 
mechanisms of SSH including private keys, and the access control mechanisms of
19
 
the server's operating system.  In particular, using groups on the server, it
20
 
is possible to provide different access privileges to different groups of
21
 
developers.
22
 
 
23
 
.. _SSH: http://www.openssh.org/
24
 
 
25
 
Setup
26
 
~~~~~
27
 
 
28
 
There is no setup required for this on the server, apart from having Bazaar
29
 
installed and SSH access available to your developers.  Using SSH
30
 
configuration options it is possible to restrict developers from using
31
 
anything *but* Bazaar on the server via SSH, and to limit what part of the
32
 
file system they can access.
33
 
 
34
 
Client
35
 
~~~~~~
36
 
 
37
 
Clients can access the branches using URLs with the ``bzr+ssh://`` prefix.  For
38
 
example, to get a local copy of the ProjectX trunk, a developer could do::
39
 
 
40
 
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk projectx
41
 
 
42
 
If the developers have write access to the ``/srv/bzr/projectx`` directory, then
43
 
they can create new branches themselves using::
44
 
  
45
 
  $ bzr branch bzr+ssh://server.example.com/srv/bzr/projectx/trunk \
46
 
  bzr+ssh://server.example.com/srv/bzr/projectx/feature-gui
47
 
 
48
 
Of course, if this isn't desired, then developers should not have write access
49
 
to the ``/srv/bzr/projectx`` directory.
50
 
 
51
 
Further Configuration
52
 
~~~~~~~~~~~~~~~~~~~~~
53
 
 
54
 
For a project with multiple branches that are all related, it is best to use a
55
 
shared repository to hold all of the branches.  To set this up, do::
56
 
 
57
 
  $ cd /srv/bzr
58
 
  $ bzr init-repo --no-trees projectx
59
 
 
60
 
The ``--no-trees`` option saves space by not creating a copy of the working
61
 
files on the server's filesystem.  Then, any branch created under
62
 
``/srv/bzr/projectx`` (see `Migration <migration.html>`_ for some ways to do
63
 
this) will share storage space, which is particularly helpful for branches that
64
 
have many revisions in common, such as a project trunk and its feature
65
 
branches.
66
 
 
67
 
If Bazaar is not installed on the user's path or not specified in the SSH
68
 
configuration, then a path can be specified from the client with the
69
 
``BZR_REMOTE_PATH`` environment variable.  For example, if the Bazaar executable
70
 
is installed in ``/usr/local/bzr-2.0/bin/bzr``, then a developer could use::
71
 
 
72
 
  $ BZR_REMOTE_PATH=/usr/local/bzr-2.0/bin/bzr bzr info \
73
 
  bzr+ssh://server.example.com/srv/bzr/proectx/trunk
74
 
 
75
 
to get information about the trunk branch.  The remote path can also be
76
 
specified in Bazaar's configuration files for a particular location.  See
77
 
``bzr help configuration`` for more details.
78
 
 
79
 
If developers have home directories on the server, they can use ``/~/`` in
80
 
URLs to refer to their home directory.  They can also use ``/~username/`` to
81
 
refer to the home directory of user ``username``.  For example, if there are two
82
 
developers ``alice`` and ``bob``, then Bob could use::
83
 
 
84
 
  $ bzr log bzr+ssh://server.example.com/~/fix-1023
85
 
 
86
 
to refer to one of his bug fix branches and::
87
 
 
88
 
  $ bzr log bzr+ssh://server.example.com/~alice/fix-2047
89
 
  
90
 
to refer to one of Alice's branches. [#]_
91
 
 
92
 
.. [#] The version of Bazaar installed on the server must be at least 2.1.0b1 
93
 
       or newer to support ``/~/`` in bzr+ssh URLs.
94
 
 
95
 
Using a restricted SSH account to host multiple users and repositories
96
 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
97
 
 
98
 
Once you have a bzr+ssh setup using a shared repository you may want to share
99
 
that repository among a small set of developers.  Using shared SSH access enables
100
 
you to complete this task without any complicated setup or ongoing management.
101
 
 
102
 
To allow multiple users to access Bazaar over ssh we can allow ssh access to a common
103
 
account that only allows users to run a specific command.  Using a single account
104
 
simplifies deployment as no permissions management issues exist for the filesystem.
105
 
All users are the same user at the server level.  Bazaar labels the commits with
106
 
each users details so seperate server accounts are not required.
107
 
 
108
 
To enable this configuration we update the ``~/.ssh/authorized_keys`` to include 
109
 
command restrictions for connecting users.
110
 
 
111
 
In these examples the user will be called ``bzruser``.
112
 
 
113
 
The following example shows how a single line is configured::
114
 
 
115
 
  command="bzr --serve --inet --allow-writes --directory=/srv/bzr",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa AAA...= my bzr key
116
 
 
117
 
This command allows the user to access only bzr and disables other SSH use.  Write
118
 
access to each repository in the directory ``/srv/bzr`` has been granted with ``--allow-writes``
119
 
and can be removed for individual users that should only require read access.  The root of
120
 
the directory structure can be altered for each user to allow them to see only a subet
121
 
of the repositories available.  The example below assumes two seperate repositories
122
 
for Alice and Bob.  This method will not allow you to restrict access to part
123
 
of a repository, you may only restrict access to a single part of the directory structure::
124
 
 
125
 
  command="bzr --serve --inet --allow-writes --directory=/srv/bzr/alice/",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa AAA...= Alice's SSH Key
126
 
  command="bzr --serve --inet --allow-writes --directory=/srv/bzr/bob/",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa AAA...= Bob's SSH Key
127
 
  command="bzr --serve --inet --allow-writes --directory=/srv/bzr/",no-agent-forwarding,no-port-forwarding,no-pty,no-user-rc,no-X11-forwarding ssh-rsa AAA...= Repo Manager SSH Key
128
 
 
129
 
Alice and Bob have access to their own repository and Repo Manager
130
 
has access to the each of their repositories.  Users are not allowed access to any part of 
131
 
the system except the directory specified. The bzr+ssh urls are simplified by 
132
 
serving using ``bzr serve`` and the ``--directory`` option.
133
 
 
134
 
If Alice logs in she uses the following command for her fix-1023 branch::
135
 
 
136
 
  $ bzr log bzr+ssh://bzruser@server.example.com/fix-1023
137
 
 
138
 
If Repo Manager logs in he uses the following command to access Alice's
139
 
fix-1023::
140
 
 
141
 
  $ bzr log bzr+ssh://bzruser@server.example.com/alice/fix-1023
142