Subversion Repositories planix.SVN

.TH FOSSILCONS 8

.SH NAME

fossilcons \- fossil console commands

.SH SYNOPSIS

.B

con /srv/fscons

.PP

.PD 0.1

.B .

.I file

.PP

.B 9p

.I T-message

...

.PP

.B bind

[

.B -b|-a|-c|-bc|-ac

]

.I new

.I old

.PP

.B dflag

.PP

.B echo

[

.B -n

]

[

.I arg

...

]

.PP

.B listen

[

.B -INd

]

[

.I address

]

.PP

.B msg

[

.B -m

.I nmsg

]

[

.B -p

.I nproc

]

.PP

.B printconfig

.PP

.B srv

[

.B -APWdp

]

.I name

.PP

.B uname

.I name

[

.I id

|

.BI : id

|

.BI % newname

|

.BI = leader

|

.BI + member

|

.BI - member

]

.PP

.B users

[

.B -d

|

.B -r

.I file

]

[

.B -w

]

.PP

.B who

.sp

.PP

.B fsys

.I name

.PP

.B fsys

.I name

.B config

[

.I device

]

.PP

.B fsys

.I name

.B venti

[

.I host

]

.PP

.B fsys

.I name

.B open

[

.B -APVWar

]

[

.B -c

.I ncache

]

.PP

[

.B fsys

.I name

]

.B close

.PP

.B fsys

.I name

.B unconfig

.sp

.PP

[

.B fsys

.I name

]

.B bfree

.I addr

.PP

[

.B fsys

.I name

]

.B block

.I addr

.I offset

[

.I count

[

.I data

]]

.PP

.in +1i

.ti -1i

[

.B fsys

.I name

]

.B check

[

.B pblock

] [

.B pdir

] [

.B pfile

] [

.B bclose

] [

.B clri

] [

.B clre

] [

.B clrp

] [

.B fix

] [

.B venti

] [

.B snapshot

]

.PP

[

.B fsys

.I name

]

.B clre

.I addr

.I offsets

\&...

.PP

[

.B fsys

.I name

]

.B clri

.I files

\&...

.PP

[

.B fsys

.I name

]

.B clrp

.I addr

.I offset

\&...

.PP

[

.B fsys

.I name

]

.B create

.I path

.I uid

.I gid

.I perm

.PP

[

.B fsys

.I name

]

.B df

.PP

[

.B fsys

.I name

]

.B epoch

[[

.B -ry

]

.I n

]

.PP

[

.B fsys

.I name

]

.B halt

.PP

[

.B fsys

.I name

]

.B label

.I addr

[

.I type

.I state

.I epoch

.I epochclose

.I tag

]

.PP

[

.B fsys

.I name

]

.B remove

.I files

\&...

.PP

[

.B fsys

.I name

]

.B snap

[

.B -a

]

[

.B -s

.I src

]

[

.B -d

.I dst

]

.PP

[

.B fsys

.I name

]

.B snapclean

[

.I timeout

]

.PP

[

.B fsys

.I name

]

.B snaptime

[

.B -a

.I hhmm

]

[

.B -s

.I interval

]

[

.B -t

.I timeout

]

.PP

[

.B fsys

.I name

]

.B stat

.IR files ...

.PP

[

.B fsys

.I name

]

.B sync

.PP

[

.B fsys

.I name

]

.B unhalt

.PP

[

.B fsys

.I name

]

.B vac

.I dir

.PP

[

.B fsys

.I name

]

.B wstat

.I file

.I elem

.I uid

.I gid

.I perm

.I length

.SH DESCRIPTION

These are configuration and maintenance commands

executed at the console of a 

.IR fossil (4)

file server.

The commands are split into three groups above:

file server configuration,

file system configuration,

and file system maintenance.

This manual page is split in the same way.

.SS File server configuration

.PP

The

dot

.RI ( . )

command

reads

.IR file ,

treating each line as a command to be executed.

Blank lines and lines beginning with a 

.L #

character are ignored.

Errors during execution are printed but do not stop the script.

Note that

.I file

is a file in the name space in which

.I fossil

was started,

.I not

a file in any file system served by

.IR fossil .

.PP

.I 9p

executes a 9P transaction; the arguments

are in the same format used by

.IR 9pcon (8).

.PP

.I Bind

behaves similarly to

.IR bind (1).

It is useful when fossil

is started without devices it needs configured

into its namespace.

.PP

.I Dflag

toggles the debug flag and prints the new setting.

When the debug flag is set, all protocol messages

and information about authentication is printed to

standard error.

.PP

.I Echo

behaves identically to

.IR echo (1),

writing to the console.

.PP

.I Listen

manages the network addresses at which

fossil is listening.

With no arguments,

.I listen

prints the current list of addresses and their network directories.

With one argument, listen

.I address

starts a new listener at

.IR address ;

the

.B -d

flag causes 

.I listen

to remove the listener

at the given address.

By default, the user

.I none

is only allowed to attach on a connection after

at least one other user has successfully attached.

The

.B -N

flag allows connections from

.I none

at any time.

The

.B -I

flag causes

.I fossil

to check the IP address of incoming connections

against

.BR /mnt/ipok ,

rejecting attaches from disallowed addresses.

This mechanism is not intended for general use.

The server

.I sources.cs.bell-labs.com

uses it to comply with U.S. crytography

export regulations.

.PP

.I Msg

prints the maximum internal 9P message queue size

and the maximum number of 9P processes to

allocate for serving the queue.

The

.B -m

and

.B -p

options set the two variables.

.PP

.I Printconfig

prints the

.B config

line for each configured file system

and prints the

.B venti

line, if any, used to configure this file server.

.PP

.I Srv

behaves like listen but uses

.BI /srv/ name

rather than a network address.

With the

.B -p

flag, 

.I srv 

edits a list of console services rather than 9P services.

With no arguments,

.I srv

prints the current list of services.

With one argument, srv

.I name

starts a new service at

.IR /srv/name ;

the

.B -d

flag causes 

.I srv

to remove the named service.

See the

.I [fsys] open

command below for a description of the

.B -APW

options.

.PP

.I Uname

manipulates entries in the user table.

There is no distinction between users and groups:

a user is a group with one member.

For each user, the user table records:

.TF \fImembers

.PD

.TP

.I id

the string used to represent this user in the on-disk structures

.TP

.I name

the string used to represent this user in the 9P protocol

.TP

.I leader

the group's leader (see

.IR stat (5)

for a description of the special privileges held by a group leader)

.TP

.I members

a comma-separated list of members in this group

.PP

The

.I id

and

.I name

are usually the same string, but need not be.

Once an

.I id

is used in file system structures archived to Venti,

it is impossible to change those disk structures,

and thus impossible to rename the

.IR id .

The translation from

.I name

to

.I id

allows the appearance of renaming the user even

though the on-disk structures still record the old name.

(In a conventional Unix file system, the

.I id

is stored as a small integer rather than a string.)

.I Leader

and

.I members

are names, not ids.

.PP

The first argument to

.I uname

is the

.I name

of a user.

The second argument is a verb, one of:

.TF \fI%newname

.PD

.TP

.I id

create a user with name

.RI ` name '

and id

.RI ` id ;'

also create a home directory

.BI /active/usr/ uname \fR

.TP

.BI : id

create a user with name

.RI ` name '

and id

.RI ` id ,'

but do not create a home directory

.TP

.BI % newname

rename user

.RI ` name '

to

.RI ` newname ,'

throughout the user table

.TP

.BI = leader

set

.IR name 's

group leader

to

.IR leader .

.TP

.BI =

remove

.IR name 's

group leader; then all members will be

considered leaders

.TP

.BI + member

add

.I member

to

.IR name 's

list of members

.TP

.BI - member

remove

.I member

from

.IR name 's

list of members

.LP

If the verb is omitted, the entire entry for

.I name

is printed, in the form

`\fIid\fL:\fIname\fL:\fIleader\fL:\fImembers\fR.'

.LP

The end of this manual page gives examples.

.PP

.I Users

manipulates the user table.

The user table is a list of lines in the form printed

by the

.I uname

command.

The

.B -d

flag resets the user table with the default:

.IP

.EX

adm:adm:adm:sys

none:none::

noworld:noworld::

sys:sys::

glenda:glenda:glenda:

.EE

.PP

Except

.BR glenda ,

these users are mandatory: they must appear in all user

files and cannot be renamed.

.PP

The

.B -r

flag reads a user table from the named

.I file

in file system

.BR main .

The

.B -w

flag writes the table to

.B /active/adm/users

on the file system

.BR main .

.B /active/adm

and

.B /active/adm/users

will be created if they do not exist.

.PP

.I Users

.B -r

.B /active/adm/users

is automatically executed when the file system

.B main

is opened.

.PP

.I Users

.B -w

is automatically executed after each change to the user

table by the

.I uname

command.

.PP

.I Who

prints a list of users attached to each active connection.

.SS File system configuration

.I Fsys

sets the current file system to

.IR name ,

which must be configured and open (q.v.).

The current file system name is

displayed as the file server prompt.

The special name

.B all

stands for all file systems;

commands applied to

.B all

are applied to each file system in turn.

The commands

.BR config ,

.BR open ,

.BR venti ,

and

.B close

cannot be applied to

.BR all .

.PP

.I Fsys

takes as an optional argument

(after

.BR name )

a command to execute on the named file system.

Most commands require that the named file system

be configured and open; these commands can be invoked

without the

.BI fsys " name

prefix, in which case the current file system is used.

A few commands

.RB ( config ,

.BR open ,

and

.BR unconfig )

operate on unopened file systems; they require the prefix.

.PP

.I Config

creates a new file system named

.I name

using disk file

.IR device .

This just adds an entry to fossil's internal table.

If

.I device

is missing,

the

.I file

argument to

.IR fossil 's

.B -f

option will be used instead;

this allows the

.I fossil

configuration file to avoid naming the partition that it is embedded in,

making it more portable.

.PP

.I Venti

establishes a connection to the Venti server

.I host

(by default, the environment variable

.B $venti

or the network variable

.BR $venti )

for use by the named file system.

If no

.I venti

command is issued before

.IR open ,

the default Venti server will be used.

If the file system is open,

and was not opened with the

.B -V

flag,

the command redials the Venti server.

This can be used to reestablish broken connections.

It is not a good idea to use the command to switch

between Venti servers, since Fossil does not keep track

of which blocks are stored on which servers.

.PP

.I Open

opens the file system, reading the

root and super blocks and allocating an in-memory

cache for disk and Venti blocks.

The options are:

.TF "-c\fI ncache

.PD

.TP

.B -A

run with no authentication

.TP

.B -P

run with no permission checking

.TP

.B -V

do not attempt to connect to a Venti server

.TP

.B -W

allow wstat to make arbitrary changes to the user and group fields

.TP

.B -a

do not update file access times;

primarily to avoid wear on flash memories

.TP

.B -r

open the file system read-only

.TP

.BI -c " ncache

allocate an in-memory cache of 

.I ncache

(by default, 1000)

blocks

.PP

The

.I -APW

settings can be overridden on a per-connection basis

by the

.I srv

command above.

.PP

.I Close

flushes all dirty file system blocks to disk

and then closes the device file.

.PP

.I Unconfig

removes the named file system (which must be closed)

from fossil's internal table.

.br

.ne 3

.SS File system maintenance

.I Bfree

marks the block at disk address

.I addr

as available for allocation.

Before doing so, it prints a

.I label

command (q.v.)

that can be used to restore the block to its previous state.

.PP

.I Block

displays (in hexadecimal)

the contents of the block at disk address

.IR addr ,

starting at

.I offset

and continuing for

.I count

bytes or until the end of the block.

If 

.I data

(also hexadecimal)

is given, the contents in that range are

replaced with data.

When writing to a block,

.I block

prints the old and new contents,

so that the change is easily undone.

Editing blocks is discouraged.

.PP

.I Clre

zeros an entry from a disk block.

Before doing so, it prints a

.I block

command that can be used 

to restore the entry.

.PP

.I Clri

removes the internal directory entry

and abandons storage associated with

.IR files .

It ignores the usual rules for sanity, such as checking against

removing a non-empty directory.

A subsequent

.I flchk

(see

.IR fossil (4))

will identify the abandoned storage so it can be reclaimed with

.I bfree

commands.

.PP

.I Clrp

zeros a pointer in a disk block.

Before doing so, it prints a 

.I block

command that can be used to restore the entry.

.PP

.I Check

checks the file system for various inconsistencies.

If the file system is not already halted, it is halted for

the duration of the check.

If the archiver is currently sending a snapshot to Venti,

the check will refuse to run; the only recourse is to wait

for the archiver to finish.

.PP

A list of keyword options control the check.

The

.BR pblock ,

.BR pdir ,

and

.B pfile

options cause 

.I check

to print the name of each block, directory, or file encountered.

.PP

By default,

.I check

reports errors but does not fix them.

The

.BR bclose ,

.BR clri ,

.BR clre ,

and

.B clrp

options specify correcting actions that may be taken:

closing leaked blocks, clearing bad file directory entries,

clearing bad pointers, and clearing bad entries.

The

.B fix

option enables all of these; it is equivalent to

.B bclose

.B clri

.B clre

.BR clrp .

.PP

By default,

.I check

scans the portion of the active file system held in the write buffer,

avoiding blocks stored on Venti or used only in snapshots.

The

.B venti

option causes

.I check

to scan the portion of the file system stored on Venti,

and the

.B snapshot

option causes

.I check

to scan old snapshots.

Specifying

.B snapshot

causes

.I check

to take a long time;

specifying

.B venti

or

(worse)

.B venti

.B snapshot

causes

.I check

to take a very long time.

.PP

.I Create

creates a file on the current file system.

.I Uid

and

.I gid

are uids

.RI ( not

unames;

see the discussion above, in the description

of the 

.I uname

command).

.I Perm

is the low 9 bits of the permission mode of the file,

in octal.

The 

.BR a ,

.BR d ,

and

.B l

mode prefixes

set the append-only, directory, and lock bits.

The

.I perm

is formatted as described in the

.I stat

command;

creating files or directories with the

.BR snapshot (s)

bit set is not allowed.

.PP

.I Df

prints the amount of used disk space in the write buffer.

.PP

.I Epoch

sets the low file system epoch.

Snapshots in the file system are given increasing epoch numbers.

The file system maintains a low and a high epoch number,

and only allows access to snapshots in that range.

The low epoch number can be moved forward to discard old snapshots

and reclaim the disk space they occupy.

(The high epoch number is always the epoch of the currently

active file system.)

.PP

With no argument

.I epoch

reports the current low and high epoch numbers.

The command

``\fLepoch\fI n''\fR

is used to propose changing the low epoch to

.IR n .

In response, 

.I fossil

scans

.B /archive

and

.B /snapshot

for snapshots that would be discarded, printing their

epoch numbers and the

.I clri

commands necessary to remove them.

The epoch is changed only if no such paths are found.

The usual sequence of commands is (1) run epoch to

print the snapshots and their epochs, (2) clri some snapshots,

(3) run epoch again.

If the file system is completely full (there are no free blocks),

.I clri

may fail because it needs to allocate blocks.

For this situation,

the

.B -y

flag to epoch forces the epoch change even when

it means discarding currently accessible snapshots.

Note that when there are still snapshots in

.BR /archive ,

the archiver should take care

of those snapshots (moving the blocks from disk to Venti)

if you give it more time.

.PP

The

.B -r

flag to epoch causes it to remove any now-inaccessible

snapshot directories once it has changed the epoch.

This flag only makes sense in conjunction with the

.B -y