hackerbase/doc/hackerbase.1

.TH hackerbase 1 "hackerbase, May 26 2023"

.SH "NAME"
hackerbase - HackerSpace Members Database tool

See \fBEXAMPLES\fR for a quick start guide.

.SH "SYNOPSIS"

.SY hackerbase
.R [
.B \-h
.R |
.B \-license
.R ]
.YS

.SY hackerbase
.B \-info
.OP \-mi id
.OP \-mn nick
.OP "OPTIONS ..."
.YS

.SY hackerbase
.R [
.B \-print
.R |
.B \-blame
.R |
.B \-edit
.R ]
.R [
.B \-mi
.R id |
.B \-mn
.R nick ]
.OP "OPTIONS ..."
.YS

.SY hackerbase
.R [
.B \-fees
.R |
.B \-problems
.R |
.B \-status
.R |
.B \-unpaired
.R |
.B \-idstats
.R |
.B \-genid
.R |
.B \-mlsync
.R |
.B \-notify
.R |
.B \-notify3
.R |
.B \-summary
.R ]
.OP "OPTIONS ..."
.YS

.SH "ACTIONS"

.TP
.B \-h
Display brief description of all actions and options.

.TP
.B \-license
Show licensing terms. See \fBCOPYRIGHT\fR.

.TP
.B \-info
With no member specified by neither \fB-mi\fR nor \fB-mn\fR display
overall hackerbase information with organizational bodies memberships
and lists of members of various statuses.

In that case it also checks internal mailinglist membership. All
members - including suspended ones - should be subscribed this
mailinglist. No other emails should be subscribed to it.

When a member is specified, displays its information from the
database, all identified bank transactions, membership information and
a calendar showing current status of the member during given month.

.TP
.B \-print
Prints given member file with errors and warnings highlighted.

.TP
.B \-blame
Prints given member file annotated by the date of last change for each
line with errors and warnings highlithed.

.TP
.B \-edit
Starts text editor on given user member file. It uses the $EDITOR
environment variable as user's editor preference. If this variable is
unset, it uses whichever editor is found in $PATH under the name
"editor".

.TP
.B \-fees
Prints a table listing all existing members and their balance with
respect to paying their membership fees. If the \fB\-destroyed\fR
option is provided then even destroyed members are included.

If
.B \-mn nick
.R is specified, complete fee, payments and credit history with balances
by date is shown.

.TP
.B \-problems
Checks all member records for problems and if any are found, print for
each of them the information table (like \fB\-info\fR for one member)
and annotated and highlighted member file source.

.TP
.B \-status
Show members directory git repository status. Used for checking
whether there are untracked and/or uncommitted changes.

.TP
.B \-unpaired
Display a table with unpaired bank transactions with ID greater than
the last id that was manually checked. See \fB\-checked\fR option.

.TP
.B \-idstats
Returns information about used and available member IDs.

.TP
.B \-genid
Generates a valid member id that is not used yet.

.TP
.B \-mlsync
Like \fB\-mlcheck\fR but automatically ensuring the subscriptions are
according to the specification.

.TP
.B \-notify
Send notification to all members with debt greater than for one month.

.TP
.B \-notify3
Send notification to all members with debt greater than for three
months.

.TP
.B \-summary
Send weekly summary email for the Council. It includes expected
monthly income based on current members counts, table with unpaired
transactions (see \fB\-unpaired\fR), table with active members with
debt greater than for three months (see \fB\-notify3\fR) and a table
with all other active members and their membership fees balances.

.TP
.B \-list
Lists all active members nicknames, one on each line. Typically used
with \fB\-quiet\fR for usage in scripts.

.SH "OPTIONS"

.TP
.B \-config \fRfname
Initial configuration file name - should be a full path. See
\fBCONFIGURATION\fR for more information.

.TP
.B \-members \fRdir
Members base directory with all members files. See \fBFILES\fR for
more information. The value read from configuration file can be
overriden by this option.

.TP
.B \-month \fRYYYY-MM
Specify current month to see the situation at particular point in time
- usually in the past. It also sets the current day to the 1st day of
the specified month.

.TP
.B \-today \fRYYYY-MM-DD
Specify current day as with previous option. This does not affect the
computation of membership fees and payments. It does however affect
the organizational bodies membership or other members properties
recorded with day precision.

.TP
.B \-tstyle \fR[ debug | ascii | unicode ]
Use given style for table borders and separators. Defaults to "unicode".

.TP
.B \-apikey \fRfname
File with Fio API keys. See \fBFILES\fR for more information. The
value read from configuration file can be overriden by this option.

.TP
.B \-bankdir \fRdir
Directory for storing bank account statement CSV files. The value read
from configuration file can be overriden by this option. A working
"parts/" subdirectory is created by bank account statements downloader
(hb_fetch_fio) in this directory for the purpose of handling
incremental account statement downloads from the bank.

.TP
.B \-checked \fRfile
File containing the ID of the latest known incoming bank transaction
across all bank account statements. The value read from configuration
file can be overriden by this option. This file is used for the
\fB\-unpaired\fR action.

.TP
.B \-dokuwiki \fRdir
Base directory of DokuWiki installation.

.TP
.B \-count \fRcount
Maximum count of transactions shown in member detail view.

.TP
.B \-mailman \fRver
Sets the mailman version. Can be \fB2 \fRor \fB3\fR.

.TP
.B \-mailman-sql
Enable direct access to mailman 3.x SQLite3 database.

.TP
.B \-mailman3-sql-path \fRpath
Sets the full path to mailman 3.x SQLite3 database file.

.TP
.B \-from \fRemail
Specify sender email address. The value read from configuration file
can be overriden by this option.

.TP
.B \-sendmail
Actually send emails for all email-sending actions. Without this
option, the email headers and body is only printed to standard output.

.TP
.B \-mailto \fRemail
Override all outgoing emails destination. Can be used for testing what
the recipients actually receive by sending notifications to different
email address and check whether the contents of the email are really
as required.

.TP
.B \-logfile \fRfilename
Enable logging to file. Mainly useful for running from cron. Adds
timestamps to log messages.

.TP
.B \-quiet
Suppress all progress output.

.TP
.B \-mi \fRid
Specify member by ID.

.TP
.B \-mn \fRnick
Specify member by nickname.

.TP
.B \-destroyed
Show destroyed members in \fB-fees\fR action as well.

.TP
.B \-ml-all
Load all mailman list memberships to show them in members info.

.SH "FILES"

All the information about members is stored in in members file in the
members directory which is also a git repository. Bank account
statements are stored for each year separately for the purpose of
updating the data from the bank and merged together for
processing. Last checked bank transaction ID is stored in the checked
transaction file.

.SS Member Files

Before parsing the configuration file all comments are removed. The
comments start with the \fB#\fR character and continue until the end
of the line.

All empty lines and lines containing only whitespace charecters are
removed.

Remaining lines are parsed as follows - leading whitespace is stripped
and first token comprised of non-whitespace characters is taken as
configuration key. The remainder of the line without leading
whitespace is then taken as given configuration option value.

This pre-processed source is scanned for mandatory known single-keys:

.RS
.IP \[bu] 2
nick - member username (nickname)
.IP \[bu]
name - first name and surname
.IP \[bu]
mail - valid email which is used for contacting this member
.IP \[bu]
phone - either a valid phone number or information that member does
not have a registered phone
.RE

.P
The following single-keys are optional:

.RS
.IP \[bu] 2
born - year, month or exact birth date
.RE

.P
The following generic keys can be present multiple times:

.RS
.IP \[bu] 2
card - RFID card id (non-desfire) for physical access to the space
.IP \[bu]
desfire - RFID desfire card id for physical access to the space
.IP \[bu]
credit - amount added to this member balance with month or exact date
of credit and optional reason for this credit record
.RE

.P
These multi-keys are converted to keys where value is a list of all
values collected for given key.

.P
The following period start/stop keys can be present multiple times as
well:

.RS
.IP \[bu] 2
joined - month or exact date of membership start
.IP \[bu]
destroyed - month or exact date right after membership end
.IP \[bu]
studentstart - month or exact date of student status start
.IP \[bu]
studentstop - month or exact date right after student status end
.IP \[bu]
suspendstart - month or exact date when member is already considered suspended
.IP \[bu]
suspendstop - month or exact date when the member is no longer considered suspended
.RE

.P
The following organizational bodies membership start/stop keys can
also be present multiple times:

.RS
.IP \[bu] 2
chairstart - exact date when this chair was elected
.IP \[bu]
chairstop - exact date of the first day when this member is no longer a chair
.IP \[bu]
councilstart - exact date when this council member was elected
.IP \[bu]
councilstop - exact date of the first day when this member is no longer a council member
.IP \[bu]
revisionstart - exact date when this revision committee member was elected
.IP \[bu]
revisionstop - exact date of the first day when this member is no longer a revision committee member
.IP \[bu]
grantstart - exact date when this grant committee member was elected
.IP \[bu]
grantstop - exact date of the first day when this member is no longer a grant committee member
.RE

.P
All the start/stop keys are coalesced into lists of periods. If for
given period the stop key is missing an open interval is assumed. The
resulting keys are as follows:

.RS
.IP \[bu] 2
member - a list of periods when this person was a valid member
.IP \[bu]
student - a list of periods when this member was a student
.IP \[bu]
suspend - a list of periods when this member was suspended
.IP \[bu]
chair - a list of periods when this member was a chair
.IP \[bu]
council - a list of periods when this member was a council member
.IP \[bu]
revision - a list of periods when this member was a revision committee member
.IP \[bu]
grant - a list of periods when this member was a grant committee member
.RE

These keys with lists of periods are then used for determining member
status at given date (which defaults to current date).

.SS Bank Account Statements

The CSV files with bank account statements are stored in the directory
specified "bank-dir" key in \fBCONFIGURATION\fR or given as
command-line option \fB\-bankdir\fR.

In the directory with bank account statements a subdirectory named
"parts/" is maintained which contains the account statements for
distinct years and only those which need an update are downloaded
regularly. Any account statement for particular year is considered as
up-to-date if it has been downloaded on January 2nd or later the
following year.

The format of the files is the same as the format provided by the Fio
bank API.

.SS Last Checked Transaction ID File

A file specified under the "checked-file" key in \fBCONFIGURATION\fR
or given as command-line option \fB\-checked\fR contains the ID of the
last checked bank transaction across all bank account statements.

When checking for \fB\-unpaired\fR transactions, only transactions
with ID greater than the numeric value stored in this file are
considered.

No comments, whitespace, or any other content is allowed in this file.

.SH "CONFIGURATION"

The default path with the initial hackerbase configuration is stored
in "/etc/hackerbase" but this can be overriden by \fB\-config\fR
command-line option.

The basic parsing is the same as with \fBMember Files\fR. But after
getting a list of pairs of keys with values, no further processing is
performed.

A sample configuration for Brmlab installation in "/etc/hackerbase"
is:

.RS
.EX
# hackerbase sample configuration file

# Where is the git repository with member files 
members-directory /root/sap/members

# Path to Fio API keys
apikeys-file /root/sap/apikey.ntlm

# Directory for storing the bank files
bank-dir /root/sap/

# Where to find last checked Fio transaction id
checked-file /root/sap/checked.ntlm  

# Global sender for any emails sent by the system
email-from Brmlab - Rada <rada@brmlab.cz>

# Where to send membership fees summary mailto
summary-mailto rada@brmlab.cz
.EE
.RE

.SH "EXAMPLES"

These examples provide a quick start guide for using this tool in
common situations.

.SS "Allocating an ID for a New Member"

To allocate a new but unused valid member id, use:

.RS
.EX
hackerbase -genid
.EE
.RE

.SS "Creating a New Member"

Currently this has to be performed manually.

Firstly allocate a new ID (see above).

Go to members base directory - the git repository specified by the
\fBmembers-directory\fR configuration option or \fB\-members\fR
command-line option. Create a file with the name containing only the
new 4-digit id. Add mandatory fields:

.RS
.EX
cat <<EOF >1234
nick NickName
name GivenName SurName
mail user.name@domain.tld
phone +420123456789
joined 2023-05
EOF
.EE
.RE

The "1234" must be replaced with the newly allocated member ID and
"2023-05" with the first month this member is an actual member. Then a
compatibility symbolic link has to be created:

.RS
.EX
ln -s NickName 1234
.EE
.RE

After checking the correctnes of the new member file, everything
should be commited to the git repository:

.RS
.EX
git add 1234 NickName
git commit -am "council-member: added new member NickName"
.EE
.RE

The "council-member" part should be replaced with the nickname of the
council member performing the addition.

.SS "Checking for Problems"

To see any members and/or member files with problems, use:

.RS
.EX
hackerbase -problems
.EE
.RE

See \fB\-problems\fR action above for more details.

.SS "Overview"

To get the overview, use the generic information action:

.RS
.ES
hackerbase -info
.EE
.RE

This prints the current members of all organizational bodies, active
members, suspended members, soon-to-expire suspended members and
debtors with debt greater than membership fee for three months.

.SS "Export Data for BrmDoor"

BrmDoor project expects separate files for generic RFID cards and
desfire cards. To generate the files, used:

.RS
.EX
hackerbase -gencards cards.txt cards_desfiter.txt
.EE
.RE

Any filenames can be used but the names used in examples are what the
BrmDoor expects.

.SH "COPYRIGHT"

Copyright (c) 2023 Brmlab, z.s.

.MT dominik.pantucek@trustica.cz
Dominik Pantůček
.ME

.B ISC License

Permission to use, copy, modify, and/or distribute this software
for any purpose with or without fee is hereby granted, provided
that the above copyright notice and this permission notice appear
in all copies.

THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR
CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

.SH "AUTHOR"

.MT dominik.pantucek@trustica.cz
Dominik Pantůček
.ME