<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
  <!ENTITY package "repair">
  <!ENTITY date    "April 2004">
]>

<refentry>
<refentryinfo>
    <address><email>coda@cs.cmu.edu</email></address>
    <copyright>
	<year>1989-2004</year>
	<holder>Carnegie Mellon University</holder>
    </copyright>
    <date>&date;</date>
</refentryinfo>

<refmeta>
    <refentrytitle>&package;</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Coda Distributed File System</refmiscinfo>
</refmeta>

<refnamediv>
    <refname>&package;</refname>
    <refpurpose>Repair conflicts in the Coda Distributed File
    System</refpurpose>
</refnamediv>

<refsynopsisdiv>
    <cmdsynopsis>
	<command>repair</command>
	<arg choice=req>-d</arg>
    </cmdsynopsis>
    <cmdsynopsis>
	<command>repair</command>
	<arg choice=req>-allowclear</arg>
    </cmdsynopsis>
    <cmdsynopsis>
	<command>repair</command>
	<arg choice=req>object_in_conflict</arg>
	<arg choice=req>fixfile</arg>
	<arg>repair_options</arg>
    </cmdsynopsis>
</refsynopsisdiv>

<refsect1>
    <title>DESCRIPTION</title>
    <para>The Coda repair tool allows you to manually resolve two kinds
    of conflicts resulted from partitioned updates. Server-server
    conflicts are conflicting mutations performed on partitioned servers
    that can not be automatically resolved. Local-global conflicts are
    caused by mutations performed on a disconnected client that are in
    conflict with the global server state.
    </para>
    <!-- <para><command>repair</command> uses the <em>ci</em> command
    interpreter to present its user interface or repair commands may be
    invoked from the command line. Several instructions may appear on a
    single line separated by semicolons. You can abbreviate command,
    variable, and help topic names. To send output into a file, end the
    command line with &gt; filename.
    </para> -->
    <para>To use the repair tool interactively, type
    <command>repair</command> at the command prompt.
    </para>
    <para>Server-Server conflicts can be repaired from the command line
    without entering interactive mode. This is useful if you need to
    repair many conflicts within a volume at a time and wish to write a
    shell script. Please see the <emphasis>EXAMPLES</emphasis> section
    for examples on invoking complete repair sequences from the command
    line.
    </para>
    <para>A description of the <command>repair</command> commands follows:
    </para>

    <variablelist>
	<varlistentry>
	<term><command>beginrepair</command>
	<replaceable>object</replaceable></term>
	<listitem>
	    <para>verifies that <replaceable>object</replaceable> is
	    indeed in conflict. It will print out messages to indicate
	    whether the current repair session is for server-server
	    conflict or local-global conflict.
	    </para>
	    <para>For a server-server repair session, this command locks
	    the corresponding volume and and mounts its individual
	    replicas read-only. It will inform the users to only use the
	    <command>comparedirs</command>, <command>dorepair</command>
	    and <command>removeinc</command> commands to repair the conflict.
	    </para>
	    <para>For a local-global repair session, both local and
	    global replicas of <replaceable>object</replaceable> are
	    visible at <emphasis>object/local</emphasis> (read-only) and
	    <emphasis>object/global</emphasis> (mutable and serving as
	    the workspace for storing the repair result for
	    <replaceable>object</replaceable>). You need to iterate
	    through the current sessions
	    <emphasis>local-mutations-list</emphasis> containing all the
	    local updates to <replaceable>object</replaceable> and its
	    descendants. Each operation in
	    <emphasis>local-mutations-list</emphasis> must be accounted
	    for and Venus maintains the
	    <emphasis>current-mutation</emphasis> being iterated. Use
	    the <command>checklocal</command> command to find out the
	    conflict between the <emphasis>current-mutation</emphasis>
	    and the server state. Note that not all local mutations are
	    necessarily in conflict, and you can use the
	    <command>listlocal</command> command to see all the
	    operations in <emphasis>local-mutations-list</emphasis>. You
	    can advance the iteration to the next operation using either
	    the <command>preservelocal</command> or the
	    <command>discardlocal</command> command with the former
	    replaying the <emphasis>current-mutation</emphasis>
	    operation on the relevant global replicas. To speed up the
	    iteration, the <command>preservealllocal</command> command
	    repeats <command>preservelocal</command> until the
	    <emphasis>local-mutations-list</emphasis> is exhausted or
	    the first replay failure. Similarly, the
	    <command>discardalllocal</command> command repeats
	    <command>discardlocal</command> until exhausting the
	    <emphasis>local-mutations-list</emphasis>. You can use
	    external tools such as
	    <citerefentry>
		<refentrytitle>emacs</refentrytitle>
		<manvolnum>1</manvolnum>
	    </citerefentry>
	    to make direct updates on needed replicas under
	    <emphasis>object/global</emphasis>. Use the
	    <command>quit</command> command to either commit or abort
	    the session.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>quit</command></term>
	<listitem>
	    <para>If the current session is repairing a server-server
	    conflict, this command releases all the volume-level locks
	    and causes the repair tool to return to the shell. If the
	    current session is repairing a local-global conflict, this
	    command asks you whether to commit or abort the repair
	    session. If you answer yes, the mutations performed on the
	    relevant global replicas will be committed to the servers.
	    Otherwise, the repair result will be aborted as if this
	    repair session has never happened.</para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>help</command></term>
	<listitem>
	    <para>Prints out a help message.</para>
	</listitem>
	</varlistentry>
    </variablelist>

    <para>Use the following commands to repair a server-server conflict:
    </para>

    <variablelist>
	<varlistentry>
	<term><command>comparedirs</command>
	<replaceable>object</replaceable>
	<replaceable>fixfile</replaceable>
	[ -acl <replaceable>user</replaceable>
	<replaceable>rwlidka</replaceable> ]
	[ -mode <replaceable>newmode</replaceable> ]
	[ -owner <replaceable>username</replaceable> ]
	</term>
	<listitem>
	    <para>Compares the mounted read-only replicas of a directory
	    in conflict and prints the repair commands in fixfile to
	    make the replicas identical. To print out the repair
	    commands on your terminal give stdout as the pathname for
	    fixfile. Compensating actions for Name/Name conflicts and
	    Update/Update conflicts are not given. The user is only told
	    about their existence and required to edit the fixfile
	    manually. You should have already done a
	    <command>beginrepair</command> on
	    <replaceable>object</replaceable> and this command works
	    only if <replaceable>object</replaceable> is a directory.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>dorepair</command>
	<replaceable>object</replaceable>
	<replaceable>fixfile</replaceable>
	</term>
	<listitem>
	    <para>Does the actual repair of an object.  If the  repair
	    succeeds,  each accessible replica will be marked
	    consistent. You will be prompted for the arguments if they
	    are missing, and  will be  asked  to confirm the repair.
	    You should have already done a
	    <command>beginrepair</command> on this object (or on on some
	    other object in this volume.). If
	    <replaceable>object</replaceable> is a file or symbolic
	    link, <replaceable>fixfile</replaceable> must  provide its
	    new  contents.  If <replaceable>object</replaceable> is a
	    directory, <replaceable>fixfile</replaceable> must provide a
	    sequence of directory repair commands for each replica. The
	    format of fixfile for directories is as follows:
<programlisting>
replica &lt;servername&gt; &lt;id of replica1&gt;
    &lt;repair commands for replica1&gt;
replica &lt;servername&gt; &lt;id of replica2&gt;
    &lt;repair commands for  replica2&gt;
and so on
</programlisting>
	    </para>
	    <para>Repair commands are given one per line.  Blank lines
	    are ok. <emphasis>id of replica1</emphasis>, <emphasis>id of
	    replica2</emphasis>, etc. are  numbers that identify each
	    replica.  These are the same as the volume  ids  of
	    read-write volumes corresponding to a replicated volume.
	    The volume ids can be obtained by doing an ls on the
	    inconsistent object, after the
	    <command>beginrepair</command> command has succeeded.  The
	    directory repair commands are:
<programlisting>
createf &lt;filename&gt; &lt;fid.0&gt; &lt;fid.1&gt; &lt;fid.2&gt;
creates &lt;symlinkname&gt; &lt;fid.0&gt; &lt;fid.1&gt; &lt;fid.2&gt;
createl &lt;linkname&gt; &lt;fid.0&gt; &lt;fid.1&gt; &lt;fid.2&gt;
created &lt;dirname&gt; &lt;fid.0&gt; &lt;fid.1&gt; &lt;fid.2&gt;
removefsl  &lt;filename or symlinkname or linkname&gt;
removed  &lt;dirname&gt;
mv &lt;srcname&gt; &lt;tgtname&gt;
    &lt;src &lt;fid.0&gt; &lt;fid.1&gt; &lt;fid.2&gt;&gt;
    &lt;target &lt;fid.1&gt; &lt;fid.2&gt;&gt;
setacl  &lt;username&gt; [rwlikda]
delacl  &lt;username&gt;
setmode &lt;newmode&gt;
setowner &lt;new owner name&gt;
setmtime &lt;new modified time&gt;
</programlisting>
	    </para>
	    <para>Note that for the <command>setacl</command> command,
	    the short form access rights of <option>all</option> and
	    <option>none</option> can also be used.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>removeinc</command>
	<replaceable>object</replaceable>
	</term>
	<listitem>
	    <para>Removes the inconsistent
	    <replaceable>object</replaceable> if it is file or a
	    symbolic link. If the object is a directory, all the
	    descendants of the object will be removed in all the
	    accessible replicas and the directory itself will be removed
	    as long as its replicas are identical. If the owner or the
	    ACL of the directory replicas are different, you have to
	    repair the conflict first.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>clearinc</command>
	<replaceable>object</replaceable>
	</term>
	<listitem>
	    <para>Compares the mounted read only replicas of a directory
	    in conflict and if the replicas are identical it clears the
	    inconsistency flag of the replicas. Otherwise it will inform
	    you about the inequality of the replicas. You should run the
	    <command>comparedirs</command> command to find out the cause
	    of conflict. This command should be used only for
	    directories. Files and symbolic links are cleared of their
	    inconsistency with the <command>dorepair</command> command.
	    </para>
	</listitem>
	</varlistentry>
    </variablelist>

    <para>The following commands are used only for repairing
    local-global conflicts:
    </para>

    <variablelist>
	<varlistentry>
	<term><command>checklocal</command></term>
	<listitem>
	    <para>Checks to see if the
	    <emphasis>current-mutation</emphasis> being iterated by the
	    current local-global repair session is in conflict with the
	    server state. It displays the operator and operand (s) of
	    the <emphasis>current-mutation</emphasis> operation and
	    indicates whether it is in conflict with the relevant server
	    replicas. If it is in conflict, a brief reason of the
	    conflict is given. Note that this command does not advance
	    the iteration of the
	    <emphasis>local-mutations-list</emphasis>.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>discardlocal</command></term>
	<listitem>
	    <para>Simply advances the iteration of the
	    <emphasis>local-mutations-list</emphasis> of the current
	    local-global repair session to the next operation. Use this
	    command when the user does not want the
	    <emphasis>current-mutation</emphasis> operation to have any
	    effect on the repair result.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>preservelocal</command></term>
	<listitem>
	    <para>Tries to replay the
	    <emphasis>current-mutation</emphasis> of the current
	    local-global repair session on the relevant global replicas.
	    In other words, it will try to preserve the effect of the
	    <emphasis>current mutation</emphasis> in the repair result.
	    If the replay succeeds, the iteration of
	    <emphasis>local-mutations-list</emphasis> will be advanced
	    to the next operation. The effect of the replay is visible
	    only on this client and not on the server until the repair
	    result is successfully committed. If the replay fails,
	    information about the reason of the failure will be
	    displayed.  
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>discardalllocal</command></term>
	<listitem>
	    <para>Repeatedly performs the
	    <command>discardlocal</command> command until the
	    <emphasis>local-mutations-list</emphasis> is exhausted. Its
	    effect is to finish the iteration and discard the effect of
	    all the remaining mutations on the repair result.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>preservealllocal</command></term>
	<listitem>
	    <para>Repeatedly performs the
	    <command>preservelocal</command> command until the first
	    failure or the iteration of
	    <emphasis>local-mutations-list</emphasis> is exhausted. This
	    command is used if the user wants to preserve the effect of
	    all the remaining mutation operations in the repair result.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>listlocal</command></term>
	<listitem>
	    <para>Prints out all the mutation operations in the
	    <emphasis>local-mutations-list</emphasis> of the current
	    local-global repair session.
	    </para>
	</listitem>
	</varlistentry>

	<!-- <varlistentry>
	<term><command>setglobalview</command></term>
	<listitem>
	    <para>If the current local-global repair session is
	    repairing a conflict on <replaceable>object</replaceable>
	    given as the argument to the <command>beginrepair</command>
	    command, the global replica of
	    <replaceable>object</replaceable> is visible at
	    <emphasis>object/global</emphasis>. This command allows the
	    global replica of <replaceable>object</replaceable> to be
	    visible at the original location (pathname) of
	    <replaceable>object</replaceable>.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>setlocalview</command></term>
	<listitem>
	    <para>If the current local-global repair session is
	    repairing a conflict on <replaceable>object</replaceable>
	    given as the argument to the <command>beginrepair</command>
	    command, the local replica of
	    <replaceable>object</replaceable> is visible at
	    <emphasis>object/local</emphasis>. This command allows the
	    local replica of <replaceable>object</replaceable> to be
	    visible at the original location (pathname) of
	    <replaceable>object</replaceable>.
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>setmixedview</command></term>
	<listitem>
	    <para>If the current local-global repair session is
	    repairing a conflict on <replaceable>object</replaceable>
	    given as the argument to the <command>beginrepair</command>
	    command, this command restore the default form of
	    local-global conflict representation in which the local
	    replica is visible at <emphasis>object/local</emphasis> and
	    the global replica is visible at
	    <emphasis>object/global</emphasis>.
	    </para>
	</listitem>
	</varlistentry> -->
    </variablelist>

    <para>The following commands existed in old versions but are no
    longer supported:
    </para>

    <variablelist>
	<varlistentry>
	<term><command>showreplicas</command>
	<replaceable>object</replaceable>
	</term>
	<listitem>
	    <para>Shows the names of the individual replicas of
	    <replaceable>object</replaceable>, and the pathnames by
	    which these replicas may be examined read-only. A
	    <command>beginrepair</command> must have been done earlier
	    on this object (or on another object in the same volume).
	    </para>
	</listitem>
	</varlistentry>

	<varlistentry>
	<term><command>unlockvolume</command>
	<replaceable>pathname</replaceable>
	</term>
	<listitem>
	    <para>Tells Venus to unlock the specified  volume  in
	    repair.   No check  is done to see if you locked the volume
	    during this repair session.  The primary use of this command
	    is to unlock volumes that were locked during a previous,
	    aborted, invocation of the repair tool.  The command will
	    fail if Venus discovers that you do not hold the repair lock
	    on the server.   This could happen, for example, if your
	    aborted repair occurred on another workstation, or if you
	    were not repairing the volume in the first place.
	    </para>
	</listitem>
	</varlistentry>
    </variablelist>
</refsect1>

<refsect1>
    <title>EXAMPLES</title>
    <para>This will cause repair to examine the object "common",
    generate a fix file for it and in addition to the contents of the
    fix file, and set the acl for hmpierce to <option>rlidwka</option> on the
    replica.
<programlisting>
repair common /tmp/fix -acl hmpierce all
</programlisting>
    </para>
    
    <para>The same repair would look like this in interactive mode:
<programlisting>
repair> beginrepair common
repair> comparedirs common /tmp/fix -acl hmpierce all
repair> dorepair common /tmp/fix 
repair> endrepair
repair> quit
</programlisting>
    </para>
</refsect1>

<refsect1>
    <title>AUTHORS</title>
    <para>
    <itemizedlist>
    <listitem><para>M. Satyanarayanan, 1989, Created</para>
    </listitem>
    <listitem><para>Puneet Kumar, 1991, Substantially revised</para>
    </listitem>
    <listitem><para>Joshua Raiff, 1993, Created man page</para>
    </listitem>
    <listitem>
	<para>Qi Lu, 1995, Added local-global repair commands and
	revised man page</para>
    <listitem>
	<para>Henry M. Pierce, 1998, updated for command line
	options</para>
    </listitem>
    <listitem><para>Jan Harkes, 2004, converted to DocBook 4.1</para>
    </listitem>
    </itemizedlist>
    </para>
</refsect1>
</refentry>

