575 lines
14 KiB
Groff
575 lines
14 KiB
Groff
.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 \-mlcheck
|
|
.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.
|
|
|
|
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.
|
|
|
|
.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 \-mlcheck
|
|
Check internal mailinglist membership. All members - including
|
|
suspended ones - should be subscribed this mailinglist. No other
|
|
emails should be subscribed to it.
|
|
|
|
.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.
|
|
|
|
.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 \-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 "jendasap-checked" 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
|
|
jendasap-checked /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"
|
|
Dominik Pantůček <dominik.pantucek@trustica.cz>
|