From d3656a1a9618daefaeb3b271a52b3aec53ab8ad1 Mon Sep 17 00:00:00 2001
From: Mark Linimon <linimon@FreeBSD.org>
Date: Tue, 18 Dec 2012 03:52:50 +0000
Subject: [PATCH]  - Document how to export some variables and change some of
 the initial    setup commands to make them cut-and-pasteable.

 - Document that the new zfsadmin tool creates a zfs permission set
   to allow the portbuild user to manage the entire volume, thus
   obviating the need for privilege escalation for that case.

 - Note that this also means that the background svn update processes
   no longer need to live in the root crontab.

 - Document how to fold the exported variables back into server.conf.

 - Finally, note that the qmanager initial command has also been automated.
---
 .../articles/portbuild/article.xml            | 104 +++++++++++++-----
 1 file changed, 79 insertions(+), 25 deletions(-)

diff --git a/en_US.ISO8859-1/articles/portbuild/article.xml b/en_US.ISO8859-1/articles/portbuild/article.xml
index 8ee914551e..fccf032988 100644
--- a/en_US.ISO8859-1/articles/portbuild/article.xml
+++ b/en_US.ISO8859-1/articles/portbuild/article.xml
@@ -2820,6 +2820,12 @@ ln -s ../<replaceable>arch</replaceable>/archive/errorlogs <replaceable>arch</re
 	    <literal>'*'</literal> password.</para>
 	</step>
 
+	<step>
+	  <para>Export that value for a later initialization step:
+	    <programlisting>&prompt.root; export PORTBUILD_USER=<replaceable>portbuild</replaceable></programlisting>
+	  </para>
+	</step>
+
 	<step>
 	  <para>Add the following to <filename>/boot/loader.conf</filename>:<screen>
 console="vidconsole,comconsole"</screen>
@@ -2981,7 +2987,7 @@ sysutils/zfs-stats</screen>
 
 	<step>
 	  <para>Create the mountpoint.</para>
-	    <programlisting>&prompt.root; mkdir -p /<replaceable>a</replaceable></programlisting>
+	    <programlisting>&prompt.root; mkdir -p ${ZFS_MOUNTPOINT}</programlisting>
 	</step>
 
 	<step>
@@ -2991,22 +2997,40 @@ sysutils/zfs-stats</screen>
 	  <example>
 	    <title>Creating a <application>zfs</application> volume for portbuild</title>
 
-<screen>&prompt.root; zpool create <replaceable>a</replaceable> mirror da1 da2 mirror da3 da4 mirror da5 da6 mirror da7 da8</screen>
+<screen>&prompt.root; zpool create ${ZFS_VOLUME} mirror da1 da2 mirror da3 da4 mirror da5 da6 mirror da7 da8</screen>
 	  </example>
 	</step>
 
       </procedure>
 
+      <note>
+	<para>We will define a <application>zfs</application>
+	  <literal>permission set</literal> below, so that the
+	  <replaceable>portbuild</replaceable> user may administer this
+	  volume without having to have root privileges.</para>
+      </note>
+
     </sect2>
 
-    <sect2 id="pointyhat-repo">
-      <title>Setting up and configuring the <application>portbuild</application> repository</title>
+    <sect2 id="portbuild-repo-setup">
+      <title>Setting up the <application>portbuild</application> repository</title>
+
+      <para>The following steps need to be done as euid root.</para>
 
       <procedure>
 
+	<step>
+	  <para>Select an <application>svn</application> repository
+	    and export it.  See the
+	    <ulink url="&url.books.handbook;/mirrors-svn.html">&os; Handbook</ulink>
+	    for the currently supported list.
+	    <programlisting>&prompt.root; export VCS_REPOSITORY=<replaceable>svn://svn0.us-east.FreeBSD.org</replaceable></programlisting>
+	  </para>
+	</step>
+
 	<step>
 	  <para>Create the <filename>portbuild</filename> directory:<screen>
-&prompt.root; mkdir -p /<replaceable>a</replaceable>/portbuild
+&prompt.root; mkdir -p ${ZFS_MOUNTPOINT}/portbuild
 </screen>
 	  </para>
 	</step>
@@ -3014,16 +3038,15 @@ sysutils/zfs-stats</screen>
 	<step>
 	  <para>Create and mount a new <application>zfs</application>
 	    filesystem on it:
-	    <screen>zfs create -o mountpoint=/<replaceable>a</replaceable>/portbuild <replaceable>a</replaceable>/portbuild</screen>
+	    <screen>zfs create -o mountpoint=${ZFS_MOUNTPOINT}/portbuild ${ZFS_VOLUME}/portbuild</screen>
 	  </para>
 	</step>
 
 	<step>
 	  <para>Set up the directory:<screen>
-&prompt.root; cd /<replaceable>a</replaceable>/portbuild
-&prompt.root; chown <replaceable>portbuild</replaceable>:<replaceable>portbuild</replaceable> .
-&prompt.root; chmod 775 .
-&prompt.root; ln -sf /<replaceable>a</replaceable>/portbuild /var/portbuild
+&prompt.root; chown ${PORTBUILD_USER}:${PORTBUILD_USER} ${ZFS_MOUNTPOINT}/portbuild
+&prompt.root; chmod 775 ${ZFS_MOUNTPOINT}/portbuild
+&prompt.root; ln -sf ${ZFS_MOUNTPOINT}/portbuild /var/portbuild
 </screen>
 	  </para>
 
@@ -3033,19 +3056,29 @@ sysutils/zfs-stats</screen>
 	  </note>
 	</step>
 
-	<step>
-	  <para>Set up an account with subversion config files
-	    installed.  Again, we generally use
-	    <replaceable>portbuild</replaceable>.</para>
-	</step>
+      </procedure>
+
+      <para>The next step needs to be done as the
+	<replaceable>portbuild</replaceable> user.</para>
+
+      <procedure>
 
 	<step>
-	  <para>As that user, set up the repository:<screen>
-&prompt.user; svn checkout svn://svn.freebsd.org/base/projects/portbuild /<replaceable>a</replaceable>/portbuild
+	  <para>set up the repository:<screen>
+&prompt.user; svn checkout svn://${VCS_REPOSITORY}/base/projects/portbuild ${ZFS_MOUNTPOINT}/portbuild
 </screen>
-	    </para>
+	  </para>
 	</step>
 
+      </procedure>
+
+    </sect2>
+
+    <sect2 id="portbuild-repo-configuration">
+      <title>Configuring the <application>portbuild</application> files</title>
+
+      <procedure>
+
 	<step>
 	  <para>Configure how build slaves will talk to your server
 	    by making the following changes to
@@ -3111,10 +3144,15 @@ sysutils/zfs-stats</screen>
 	    <listitem>
 	      <para>Set <makevar>UPLOAD_DIRECTORY</makevar>,
 		<makevar>UPLOAD_TARGET</makevar>, and
-		<makevar>UPLOAD_USER</makevar> as approprite
+		<makevar>UPLOAD_USER</makevar> as appropriate
 		for your site.</para>
 	    </listitem>
 
+	    <listitem>
+	      <para>Set <makevar>VCS_REPOSITORY</makevar> to whatever
+		you chose above.</para>
+	    </listitem>
+
 	    <listitem>
 	      <para>Set <makevar>MASTER_URL</makevar> to the http
 		URL of your server.  This will be stamped into the
@@ -3135,6 +3173,13 @@ sysutils/zfs-stats</screen>
 
       <procedure>
 
+	<step>
+	  <para>As euid root, set up the <application>zfs</application>
+	    <literal>permission set</literal>:
+	    <programlisting>&prompt.root; ${ZFS_MOUNTPOINT}/tools/zfsadmin</programlisting>
+	  </para>
+	</step>
+
 	<step>
 	  <para>For each architecture, follow the steps in
 	    <xref linkend="new-arch-pre-qmanager"/>.</para>
@@ -3165,8 +3210,15 @@ qmanager.sh</screen>
 
 	<step>
 	  <para>Initialize the <application>qmanager</application>
-	    database's acl list:<screen>
-&prompt.root; python /var/portbuild/qmanager/qclient add_acl name=deny_all uidlist= gidlist= sense=0
+	    database's acl list:<para>
+
+	  <note>
+	    <para>This should now be automatically done for you by
+	      the first <command>build</command> command.</para>
+	  </note>
+
+	  <para><screen>
+&prompt.root; python /<replaceable>a</replaceable>/portbuild/qmanager/qclient add_acl name=deny_all uidlist= gidlist= sense=0
 </screen></para>
 	</step>
 
@@ -3180,14 +3232,16 @@ qmanager.sh</screen>
       <procedure>
 
 	<step>
-	  <para>Run the following commands manually to create the
+	  <para>As the <replaceable>portbuild</replaceable> user,
+	    run the following commands manually to create the
 	    <literal>src</literal> and <literal>ports</literal>
 	    repositories, respectively:<screen>
-&prompt.user; sudo /var/portbuild/scripts/updatesnap.ports
-&prompt.user; sudo /var/portbuild/scripts/updatesnap
+&prompt.user; /<replaceable>a</replaceable>/portbuild/scripts/updatesnap.ports
+&prompt.user; /<replaceable>a</replaceable>/portbuild/scripts/updatesnap
 </screen></para>
 
-	  <para>These will be periodically run from the root
+	  <para>These will be periodically run from the
+	    <replaceable>portbuild</replaceable>
 	    <filename>crontab</filename>, which you will
 	    install below.</para>
 	</step>