acst.1
1.TH ACST 1 acst\-VERSION
2.SH NAME
3acst \- Actual C-implementation of a Simple shaTag
4.
5.SH SYNOPSIS
6.B acst
7.RB [ \-dhmnqvx ]
8.IR "" < FILE ...>
9.
10.SH DESCRIPTION
11.B acst
12is a minimal and simplified implementation in C of, or rather, inspired by,
13.B shatag
14and also inspired by
15.BR cshatag .
16.P
17.B acst
18as a tool is designed to detect silent data corruption by first writing the
19mtime and the SHA256 checksum of a file into its extended attributes and then,
20upon later execution, comparing and verifying changes against both the mtime
21and checksum. For this to work, the file system intended to be verified must
22first support extended user attributes, either by being mounted with user_xattr
23enabled or by other means. Depending on how these variables differ, various
24file statuses are being reported (see the
25.B "FILE STATUSES"
26section).
27.P
28.B acst
29won't follow symlinks due to the risks of creating reference loops or
30referencing data outside of the indented scope of subdirectories.
31.B acst
32also won't descend into directories on other file systems than the one
33specified using the
34.IR FILE
35argument. Keep in mind that if multiple files with different file systems are
36specified using the
37.IR FILE
38argument, they will get traversed indifferent of each other. For example, if
39you specify two different partitions mounted on two different directories, they
40would both be traversed.
41.P
42.B acst
43reads names of files to open from standard input if the only
44.IR FILE
45argument is '-'. To open files starting with '-', use '--' to cancel parsing of
46arguments.
47.P
48.B acst
49does not aim to be format-compatible with
50.B shatag
51and uses different names for the extended attributes but similar formats for
52the extended attributes (see the
53.B COMPATIBILITY
54section).
55.
56.SH OPTIONS
57.TP
58.BR -d
59Check for duplicates among files based on stored checksums from acst's extended
60attributes. Return values when checking for duplicates are normally 0 for
61success or 1 for fatal errors (in other words, the
62.B "RETURN VALUES"
63section does not apply). Certainty of the result is, of course, dependent on
64checksums being created or corrected fairly recently as no checksums are being
65computed during the duplicate check.
66.TP
67.BR -h
68Print brief usage information to standard output and exit.
69.TP
70.BR -m
71Summarize information at end of execution.
72.TP
73.BR -n
74Don't create or update any extended file attributes. File hashing and checking
75will be performed, but no extended file attributes will be created or updated.
76.TP
77.BR -q
78Quiet mode. If specified one time
79.B ok
80files are not being reported. If
81specified two times, only
82.BR corrupt ,
83.BR backdated ,
84and
85.BR malformed
86files and errors are being reported.
87.TP
88.BR -x
89Remove acts's extended attributes (xattrs) from
90.IR FILE .
91.TP
92.BR -v
93prints version information to stderr, then exits.
94.
95.SH "RETURN VALUES"
96.TP
97.BR 0
98Success
99.TP
100.BR 1
101Wrong number of or invalid arguments.
102.TP
103.BR 2
104One or more files, including directories when executed with the recursive flag,
105could not be opened.
106.TP
107.BR 3
108One or more files is not a regular file and probably a symlink of sorts.
109.TP
110.BR 4
111Extended attributes could not be written to one or more files.
112.TP
113.BR 5
114At least one file was found to be corrupt, backdated or malformed.
115.TP
116.BR 6
117More than one type of error has occurred.
118.
119.SH "FILE STATUSES"
120During program execution and processing of each file various file statuses will
121appear on
122.BR stdout .
123Following are descriptions of these statuses.
124.TP
125.BR ok
126Checksum is correct and mtime is unchanged.
127.TP
128.BR "hash ok"
129Checksum is correct and mtime was changed.
130.TP
131.BR outdated
132Checksum is incorrect and mtime is newer than the one stored as an extended
133Attribute.
134.TP
135.BR backdated
136Checksum is incorrect and mtime is older than the one stored as an extended
137Attribute.
138.TP
139.BR malformed
140Extended attributes could not be read as otherwise intended.
141.TP
142.BR corrupt
143Checksum is incorrect but mtime stayed the same.
144.TP
145.BR disrupted
146File was modified during hash computation.
147.TP
148.BR new
149Extended attributes are missing and were added.
150.TP
151.BR "xattr removed"
152Extended attributes were removed.
153.TP
154.BR "dup"
155Duplicate of checksum among files checked.
156.
157.SH EXAMPLES
158.TP
159.BR "find /mnt/memorystick -xdev -type f | acst - > /root/acst.log"
160will use
161.B find
162to recursively traverse through files in
163/mnt/memorystick within the same file system and log the result to
164/root/acst.log.
165.TP
166.BR "find /home/user01 /strg/shr/media -type f | acst - > /root/acst.log"
167will recursively process files in both /home/user01 and /mnt/memorystick even
168if they belong to different file systems, and then log the result to
169/root/acst.log.
170.TP
171.BR "find /home/user01 /strg/shr/media -type f | acst -m - > /root/acst.log"
172will perform the same operation as above with the addition of also summarizing
173the result of the execution to the log.
174.TP
175.BR "find /mnt/memorystick -xdev -type f | acst -x - > /root/acst.log"
176will recursively process and remove extended attributes from files in
177/mnt/memorystick and log the result to /root/acst.log.
178.TP
179.BR "find /mnt/memorystick -xdev -type f | acst -d -
180will recursively check for duplicates among files in /mnt/memorystick based on
181checksums stored as extended attributes.
182.
183.SH COMPATIBILITY
184.B acst
185writes to
186.B user.acst.cs
187and
188.B user.acst.ts
189instead of the
190.B user.shatag.sha256
191and
192.B user.shatag.ts
193specified by
194.BR shatag .
195.br
196.B acst
197writes the
198.B user.acst.ts
199field with full integer nanosecond precision, while python-implemented
200.B shatag
201doesn't.
202.
203.SH AUTHOR
204Chris Noxz <chris@noxz.tech>
205.
206.SH COPYRIGHT
207Copyright \(co 2022 Chris Noxz.
208.P
209License: GPLv3+
210.P
211GNU GPL version 3 or later
212<https://www.gnu.org/licenses/licenses.html>.
213.P
214This is free software: you are free to change and redistribute it.
215There is NO WARRANTY, to the extent permitted by law.
216.
217.SH "SEE ALSO"
218.BR shatag (1),
219.BR cshatag (1),
220.BR sha256sum (1),
221.BR getfattr (1),
222.BR setfattr (1)
223.P
224The original
225.B shatag
226utility, written in python by Maxime Augier:
227.br
228https://bitbucket.org/maugier/shatag
229.br
230and
231.B cshatag
232utility, written in Go by Jakob Unterwurzacher:
233.br
234https://github.com/rfjakob/cshatag
235.
236.SH AVAILABILITY
237.P
238Up-to-date sources can be found at:
239.br
240https://noxz.tech/git/acst
241.br
242https://noxz.tech/software/acst
