p4checkpoint - routine maintenance for the p4(1) database
p4checkpoint [-a days] [-k keep] [-L logfile] [-p port] [-q|-Q] [-s percent] [-u user] p4-root
p4checkpoint -v
Performs routine periodic maintenance of the p4(1) database in a manner that
is suitable for invocation from a crontab(1) command.
p4-root denotes the root directory of the p4 database.
If it is unspecified, then the value of the P4ROOT environment variable
is used, or an error is raised if it is undefined.
The following tasks are performed in order:
-
The database integrity is verified via p4 verify -qu //....
-
Stale journal files are reported, and the time of the last checkpoint is
determined from the modification time of the most recent checkpoint file.
-
The database is checkpointed via p4d -jc.
-
The disk space usage on the p4 database volume is checked via df,
and a warning is reported if it exceeds a threshold.
-
Any messages in the p4 error log more recent than the last checkpoint are
reported to STDOUT.
-
Any checkpoint files that exceed both an age threshold and a
number-of-checkpoints-ago threshold are removed, along with any journal
files that would otherwise become stale as a result.
If a potentially serious problem is discovered at any stage, then messages
are send to STDERR and processing terminates.
That way, you can fixed any detected corruption before it propagates.
If there are no problems to report, then p4checkpoint does not produce
any output.
This is usually what you want, because then it won't generate annoying
e-mail when you run it as a crontab(1) command.
If you want to confirm that maintenance is actually occurring, then you
can look at the modification time of checkpoint files in the p4 database.
If you really want confirmation every time that it runs, then you can
make your crontab(5) entry look like this:
0 2 * * 1-5 p4checkpoint ; echo "p4checkpoint done"
- -a days
-
Set the minimum age of removed checkpoint files to days days.
Default is 7.
- -k keep
-
Set the minimum number of saved checkpoint files to keep.
Default is 3.
- -L log
-
Look in file log for server errors. Default is ``p4-root/errlog''.
Set it to ``'' to disable examining the log.
- -p port
-
Override the P4PORT environment variable with port.
- -q
-
Quiet mode. Any errors in the p4 error log containing the message ``Connection
with partner closed unexpectedly'' are ignored, because they are generally
caused by exceptional but innocuous events, such as user-interrupt.
- -Q
-
Really quiet mode.
Ignores p4 error log messages containing ``write: socket: Broken pipe'',
because they are generally caused by a P4 Client API callback throwing an
exception while the server is trying to talk to the client.
Unfortunately, such a message might instead indicate real trouble, but
if the P4 Client API is in use at your site, you might get too many of
these errors to investigate them.
Implies -q.
- -s percent
-
Set the maximum disk usage of the volume containing the p4 database to
percent percent.
A warning will be generated if this threshold is exceeded.
Default is 50%.
CAUTION: It is recommended that you avoid increasing percent well
beyond 50%.
While it is not normal for the size of the p4 database to double overnight,
it is known to happen occasionally when naive users do naive things, such
as making their own copy of everything.
You'll probably have to undo this anyway when it happens, but it's nice if
other people still get to do useful work in the meantime.
Similarly, it is a bad idea to use the volume on which the p4 database
resides for general purpose storage as well, because it's really undesirable
to lose access to the source control system just because somebody's program
went nuts and filled the disk.
- -u user
-
Run p4d and remove checkpoints as user user.
This is useful when the user that runs the p4d server is not a licensed
p4 user.
The user who invokes p4checkpoint is still required to be a licensed p4
user.
/etc/sudoers must allow the user invoking p4checkpoint to
``/bin/su user -c ...''.
This option isn't suitable for running from within a
crontab(1) command
unless /etc/sudoers specifies NOPASSWD for this operation, because there is
no tty through which to authenticate the user.
- -v
-
Print the version number and exit.
You'll get the greatest benefit from performing p4 maintenance if it is
coordinated with the periodic system backups.
Ideally, the system backups should occur immediately after p4 maintenance,
and the current journal file should be backed up before any versioned
data files.
If this is the case, then you'll always be able to restore to the point of
the previous system backup of the journal file.
Otherwise, you might have to back up as far as the last checkpoint file
that was completed before the most recent system backup started.
As a rule, you should set both the -a and -k options to guarantee
that every checkpoint winds up on at least 2 system backups, assuming that
the system backup policy is adhered to.
This provides reasonable protection from errors in the backup media, as
well as from occasional violations of the backup policy.
-
There isn't a way to specify a checkpoint/journal prefix.
Since journal and checkpoint files therefore reside on the same volume as
the database itself, they are vulnerable to a single-point failure.
This isn't really an issue, because the versioned data files are always
vulnerable to a single-point failure anyway, and the journal and checkpoint
files are useless without them.
The point of all this is that checkpointing and journaling provide a means
of recovery that is amenable to backups performed while the database is being
modified, but they are not really useful for hiding failures completely.
You need to invest in a RAID file system if that is a requirement.
-
The journal.n files are basically useless, but they might come in handy
in the unlikely event that the p4 database becomes corrupted for no apparent
reason (for example, due to a
p4d(1) bug).
Therefore, we keep them around as long as their subsequent checkpoint file.
Anders Johnson <anders@ieee.org>