QRef - Quick Reference
QRef is also on www.hotscripts.com
SYNOPSYS:
QRef - Quick Reference version 1.2 $Date: 2007/09/05 14:34:02 $
DESCRIPTION:
QRef is used to store and organize notes and data for quick reference.
QRef works under the philosophy that most people have a collection of
personal notes (usually in folder on their PC or a collection of emails)
that quickly becomes unmanageable. Much like keeping notes, each user
can have their own private register and a shared public register.
QRef makes it easy to store and find this information from the command line.
In addition to the CLI there is a web interface and an email interface.
QRef is written in Perl with a MySQL backend and uses CGI and some
Javascript. The CLI uses cookies much like a web browswer.
FEATURES
*Multiple interfaces: CLI, Web and Email(Beta)
*Fast keyword based search (and option to search entry content as well)
*Attach files of any format to an entry (e.g. Visio, PDF, Word etc)
*Entry and Attachment with document revision control
*Access control to registers with approval work-flow option
*Minimal Javascript for maximum browser compatiblity
*Export/Import utilities (text, XML, MySQL dumps)
*Installation configuration script for easy install from RPM or tarball
INSTALL:
See INSTALL.txt
ADMINISTRATION:
The command qadmin can be used for most administrative tasks (as well as
qref.cgi) such as managing users, categories and registers. The current
user must have admin permissions based on the current session cookie (shared
for qref and qadmin).
qadmin -h
PREFERENCES:
Users may configure their own preference by setting up a recourse configuration
file. The command "qref -p" will create a default ~/.qrefrc file
to edit. This file take precedence over /opt/qref/conf/qref.conf.
ACCESS CONTROL:
Qref uses cookies for both the web interface and CLI. Standard
HTML cookies with and MD5 based cookie is used for the web interface
and a cookie file (only readable by the user) for the CLI (~/.qref-cookie).
QRef user based access control is a least-access based system.
Each Register (MySQL database containing QRef entries) has an
Access Level. Each user also has an their own priviledges.
The lesser of the Register access level and the user priviledges
determine the authorization level. The two exeptions are the
and admin is always admin and the owner of a Register is always
has full access to a register. For example a user with Query+Add+Edit
priviledges accessing a Register with Query+Add rights will only
have Query+Add rights and looses the Edit rights. Conversly,
a user wit Query (read-only) priviledges accessing a Register he
owns is given Full access.
Finally, only and admin may manage users (add/remove/password resets etc).
Query+Add+Edit users and above may approve pending entries.
Register Access Levels:
1 - Full Access (includes users ability to edit categories)
2 - Query + Add + Edit (users may edit all entries)
3 - Query + Add (users may edit their own entries only)
3 - Query (read-only)
5 - Private (access via owner and admins only)
QRef user priviledge:
Query - Read Only.
Query + Add - May only edit/delete entries own entries.
Query + Add + Edit - May query/add/edit all entries.
Query+Add+Edit+Cat - May query/add/edit all entries plus categories.
Admin - Full Access to all Registers plus user management.
QRef also has the following statuses:
Pending - Enties pending approval of a moderator.
Approved - Default queries are for Approved status only.
Archive - Archived Entires.
Other - Other status.
Deleted - To be permantly deleted by emptying trash.
New entries can default to "Pending" or "Approved" for non-admin's.
If defaulting to "Pending" admin or Q+A+E user must approve the entry.
This allows for the entry to be reviewed before posting. This can be set
in by updating the DEFAULT_STATUS variable in /opt/qref/conf/qref.conf.
DOCUMENT REVISION CONTROL:
A basic Document Revision Control system exists for both entries (data
stored in MySQL or entry attachments. Ensure that REV_CONTROL is set to 1
to have document revision control turned on. It will store previous
revision in BKUP_DIR (default: /opt/qref/data/rc) in the following manner.
Currently there is no way to review infomation than by manually going
to the filesystem.
$BKUP_DIR/[REGISTER]/[ENTRY_ID]/ENTRY-YYYYMMDDHHMM
$BKUP_DIR/[REGISTER]/[ENTRY_ID]/attachment_filename.YYYYMMDDHHMM
qref.conf variables:
$REV_CONTROL = 1; #Turn on REV_CONTROL
$BKUP_DIR = "/opt/qref/data/rc"; #Where to keep REV_CONTROL files
REGISTERS:
Registers are separate areas for data to be stored which consist of
*databases (separate MySQL DB)
*attachment file archives
*catgories
Users are global per qref install instance.
qadmin -a
Add addition Register (creates MySQL database).
qadmin -m
Modify Register (change register attributes).
qadmin -r
Remove Register (Remove register from QRef but does not
delete MySQL database).
A register may be exported to a file structure with the -X option
(contains entries and attachments).
EMAIL (BETA):
QRef may be configured to have entried added via email. The script
getmail.pl may be configured to run via cron to check for mail
periodically. The Body of the message must contain the EMAIL_TOKEN
variable in the qref.conf file on a line by itself. This is a safe-
guard against spam and acts as a kind of password to prevent unwanted
entries being added. This is much less secure but can be convenient.
The email pop3 server and other variable are all set in qref.conf. By
default new entries are added as the qref user admin. Or you may create
a role user.
FILES:
/opt/qref/conf/qref.conf
/opt/qref/bin/qadmin
/opt/qref/bin/qref
/opt/qref/bin/getmail.pl
/opt/qref/data/attach
/opt/qref/data/rc
/opt/qref/doc/license_gql.txt
/opt/qref/doc/README.txt
/opt/qref/doc/INSTALL.txt
/opt/qref/doc/release_notes.txt
/opt/qref/doc/license_gql.txt
/opt/qref/install/attach.gif
/opt/qref/install/initqref.sql
/opt/qref/install/install.pl
/opt/qref/install/qref_bkup.pl.example
/opt/qref/install/qref.cgi
/opt/qref/install/qrefrc.example
/opt/qref/install/upload.cgi
/opt/qref/lib/QREF.pm
/opt/qref/web
/usr/local/bin/qref -> /opt/qref/bin/qref
/usr/local/bin/qadmin -> /opt/qadmin/bin/qadmin
BUGS AND FEATURE REQUEST:
Send bugs and enhancement requests to: bugs@zrabbit.com
See bugs.txt file to see if your bug/feature is already there.
RELEASE HISTORY:
RELEASE-1_2 2007/05/03 Added REV_CONTROL dir, bug fixes.
RELEASE-1_1 2007/02/15 Added directory structure to basedir
install via RPM
RELEASE-1_0 2006/10/09 Ok testing is over
RELEASE-0_9_9 2004/06/09 Increased security of auth levels.
Fixed minor bugs in CGI.
Added smtp interface (add entries via email)
Centralized variables in qref.conf
RELEASE-0_9_8 2004/05/06 Improved CLI syntax and display.
RELEASE-0_9_2 2003/02/04 Released under GPL on www.hotscripts.com.
RELEASE-0_9_0 2003/01/03 Initial release
AUTHOR:
Jason T. Nelson
January 2, 2003
Q & A:
Q. Unable to access qref.cgi
A. *If your cgi dir is other than cgi-bin you must update this line
in qref.conf to give the path to your cgi-bin:
$CGI_REL_PATH = "/cgi-bin/";
Q. Cookies don't seem to work and I don't have a domain. How can I make cookies work?
A. Set $DOMAIN in qref.conf to your IP address.
Q. Is there more documentation on QRef?
A. QREF.pm is documented using perldoc. To view type:
perldoc /opt/qref/lib/QREF.pm
EXAMPLES:
*** Simple Keyword search ***
[kiwi]$ qref tacacs faq <-- qref with no flags and keywords
Searching QREF for any keyword(s): tacacs
ID: 139 Keywords: TACACS FAQ
Note ID: 139 Keywords: TACACS FAQ
Status : Approved Category: Routers (18)
------------------------------------------------
*** TACACS FAQ ***
TACACS - Terminal Access Controller Access Control System
Same idea as Radius - offload the user administation to a central server.
A Cisco solution that uses a Network Access Sever (NAS)
(for example a Cisco 2511 or a 5300) for user admin.
*** Search using categories ***
[@kiwi]$ qref -c rou <-- You may abbreviate
Searching in category: Routers (18) <-- Searching by category
Searching QREF for keyword(s): <-- No keyword provided searching all
ID: 139 Keywords: TACACS FAQ
ID: 142 Keywords: CISCO CLI EXAMPLES
Found 6 entries.
Enter entry ID to view (q)uit: 200
Note ID: 200 Keywords: DEBUG
Status : Approved Category: Routers (18)
------------------------------------------------
*** Debug ***
If you are not console (e.g. you telnet'd or ssh'd in)
you need to run this command to echo debugging:
*** Failed Search for an entry based on Keyword ***
[@kiwi]$ qref XTACACS
Searching QREF for keyword(s): XTACACS
No entries found.
*** This did not find the entry as the keywords
*** match on the beginning of the word (case insensitive)
[@kiwi]$ qref -A XTACACS
Searching Keywords and Entry Contents. <-- Now searching the contents
Searching QREF for any keyword(s): XTACACS
ID: 139 Keywords: TACACS FAQ
Note ID: 139 Keywords: TACACS FAQ
Status : Approved Category: Routers (18)
------------------------------------------------
*** TACACS FAQ ***
TACACS - Terminal Access Controller Access Control System
Same idea as Radius - offload the user administation to a central server.
A Cisco solution that uses a Network Access Sever (NAS)
(for example a Cisco 2511 or a 5300) for user admin.
*** Email an entry ***
[@kiwi]$ qref -m
Enter Email Address: joe@domain.com
Enter Entry ID or Keywords: 200
*** Or non-interactively ***
[@kiwi]$ qref -m joe@domain.com 200
Emailed entry: 200 [DEBUG] to joe@domain.com Successfully!
*** Add Attachement ***
[kiwi]$ qref -f 139 update_readme
Enter ID or Keywords to attach file to: tacacs
Enter file to attach: update_readme
Searching for Keywords : tacacs
ID: 139 Keywords: TACACS FAQ
Enter entry ID to edit (q)uit: 139
Attach "update_readme" to to entry: 139 y|n ? y
Copying update_readme to /opt/qref/uploads/QREF/ - please wait...
Attachment update_readme added to entry 139 successfully.
*** Remove attachement ***
[jtnelson@kiwi qref]$ qref -F
Attachments:
1. /opt/qref/uploads/QREF/139/update_readme
Delete attachment 1 - 1 [q]uit: 1
Delete attachment: /opt/qref/uploads/QREF/139/update_readme y|n? y
Attachment /opt/qref/uploads/QREF/139/update_readme deleted
*** List Users or Search by User ***
[kiwi]$ qref -u
Query by User: -u [ or ] []
Id Username Realname Register Logged in since:
----------------------------------------------------------
1 admin Qref Admin QREF
2 jtnelson Jason T. Nelson QREF Wed Jun 2 09:08:51 2004
40 guest Read-Only Account TEST
45 email Email Role User QREF
Total 11
*** Registers ***
[kiwi]$ qref -r
Current Register (database): QREF
Registers available:
1. QREF Owner: admin Access: Full Access
2. JTN Owner: jtnelson Access: Private
3. JPERRO Owner: jperro Access: Query
Choose Register [1 - 3 q(uit)]: JTN
Register Changed to JTN
LEGAL:
This file is part of QRef.
QRef is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
QRef is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with QRef; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
CVS:
$Id: README.txt,v 1.38 2007/09/05 14:34:02 jnelson Exp $