Lubricator 2.4
---------------------------------------------------------------------
GUI HTTP search, download and disk writing
1. About
2. Features
3. Minimum requirements
4. Installation
5. GUI usage
6. Command-line usage
7. Icon tooltypes
8. Troubleshooting
9. Privacy concerns
A. Server exchange protocol
B. Changelog
C. Licenses and Copyright
1. About
---------------------------------------------------------------------
Lubricator is a combined GUI and command-line tool that allows you to
search, download and unarchive Amiga software, and to write disk images
directly from the internet to disks on your Amiga. It works fine on
machines with just a 68000 CPU and very little memory.
Supported disk image formats are ADF and DMS. Also supported is smart
unpacking of LHA and ZIP archives, and the creation of bootable disks
for running executables. Included in the GUI is (by default) an Aminet
and Pouët search facility. Lubricator can deal with simple HTML files
and display the links from a web server's directory listing, for
example.
The principal idea is to eliminate the need for a companion PC, and to
get software onto every Amiga as easily and quickly as possible -
bypassing the hassle of physical media or setting up network services
locally.
For demo connoisseurs, Lubricator makes it as convenient as possible to
watch demos (including trackmos) from the real machine, so it is easier
to resist the temptation of clicking on internet videos, or ending up in
an emulator.
See also: C. Licenses and Copyright
2. Features
---------------------------------------------------------------------
- Smart unpacking: Unpacks archives without producing file clutter.
- Async I/O, no temporary files for disk writing: Interleaves trackdisk
I/O and pumping disk images all the way through the internet right onto
your disks - it won't get any more efficient.
- Resource-saving and hardened for low memory conditions: For instance,
you can start Lubricator with just 200k of free memory and search and
download from Aminet.
- Integrated packdisk maker for producing collections of executables
(such as intros, demos and games) on a disk with a small menu.
- Special index files (dubbed 'amindex') use a simplified format that
can contain links to downloads and other addresses. If you are
interested in building your own web, download an example amindex file,
edit it, save it locally or upload it to your webserver and share it
with your friends.
3. Minimum requirements
---------------------------------------------------------------------
68000 CPU, Kickstart 2.x (v37), bsdsocket.library v3, httpclient.library
v4 (included)
Every Amiga can be connected to the network, use for example
- a PCMCIA network adapter (A600, A1200),
- or Plipbox or an ACA500+/X-Surf-500 for the A500,
- or a Zorro-II/III network card on an A2000/3000/4000.
Good TCP/IP stacks for 68000 Amigas are Roadshow and AmiTCP. AmiTCPv4 is
also part of the X-Surf-500 software package. Lubricator should also
work with the demo version of Roadshow and the freely downloadable
AmiTCPv3 from Aminet.
HTTPS and FTP downloads (as well as Pouët and Aminet searches) are
redirected to a server in my vestibule. So if you download from an URL
with the https:// scheme, the download is not really encrypted all the
way to your computer, I am man-in-the-middle. But you can set up your
own search and download server.
See also: 9. Privacy concerns
4. Installation
---------------------------------------------------------------------
Not strictly required - can run with httpclient.library in the current
directory. To install, copy httpclient.library to LIBS:, and Lubricator
wherever you want.
For unpacking, the commands lha and unzip are expected in the path.
Obviously, you can download them with Lubricator:
From GUI:
- Change to the 'Aminet' facility, enter "lha.run" as the search term.
Double-click the entry to download it to the download directory. Change
to the 'Local' facility, double-click lha.run, run it 'Normal'. 'R'eload
the 'Local' facility. Double-click LhA.guide for LhA's manual. Using a
shell or file-manager, copy lha_68k to C:lha .
- Provided that LhA is already installed, change to the 'Aminet'
facility, enter "unz550" as the search term, double-click unz550xA.lha
to download and unarchive. Using a shell or file-manager, copy UnZip to
C: .
From command-line:
# lubricator search aminet lha.run
# lubricator search aminet unz550
# lubricator get http://aminet.net/util/arc/lha.run
# lha.run
# copy lha_68k c:lha
# lubricator unpack http://aminet.net/util/arc/unz550xA.lha
# copy unzip c:
Note on UnZip:
UnZip 5.50 reports warnings for no other reason than an unset timezone
(TZ) env variable. See timezone.doc in the UnZip archive. TL;DR: To
silence these warnings, set e.g. Central European time as follows:
# setenv TZ "MET-1MEST"
# copy ENV:TZ ENVARC:
See also: 8. Troubleshooting
5. GUI usage
---------------------------------------------------------------------
Self-explanatory, unless noted otherwise. Small button captions:
'R' - Reload
'H' - Homepage or download directory
Click the cycle button (by default showing 'Index') to get to the
'Pouët' and 'Aminet' search facilities. On these facilities, use the
text field to search. Reload with an empty text field to get a list of
the latest uploads to the respective facility.
Select the 'Local' facility to browse the download directory.
Double-click items in the list to invoke their default action (e.g.
Unarchive, Write, Download, Show/Execute).
Additional keyboard shortcuts:
Tab - Cycle through facilities
Return - Activate address/search field
ESC - Abort downloading, writing, etc.
Menu functions:
- "Run Executable..." allows you to launch an executable. This function
will also set a file's executable bit if this was forgotten somehow (by
UnZip, for example).
- "Suggest Random Demos..." uses the Pouët search to suggest a random
bunch of demos.
- "Open Index file..." - to open a local 'amindex' file.
- "Make Disk from Executable..." - this function performs a quick format
on a disk, copies an executable on it, and makes it bootable. This can
greatly improve chances to get a filedemo running.
- "Packdisk Maker..." - With the packdisk maker, you can create a disk
with multiple demos/intros and a small menu. Double-click executables in
the main list to add them to the packdisk maker. Click entries in the
packdisk maker to edit their names (as they should appear in the menu).
- Bookmarks: Up to nine bookmark entries (edited in icon tooltypes).
See also: 7. Icon tooltypes for homepage and bookmarks
6. Command-line usage
---------------------------------------------------------------------
Without an address, path or search term, Lubricator starts up with the
GUI. Start the GUI in a given facility:
# lubricator SHOW local
Search in a facility:
# lubricator SEARCH aminet cranker
Show recent uploads (SHOW and SEARCH can be used interchangeably):
# lubricator SHOW pouet ""
# lubricator SEARCH aminet ""
Download a file:
# lubricator GET http://some.host/some.file
# lubricator GET http://some.host/some.file TO filename
# lubricator GET http://some.host/some.file TO RAM:
Download and unpack an archive:
# lubricator UNPACK http://some.host/some.archive TO RAM:
Write a disk image:
# lubricator WRITE http://some.host/some.dms TO df0:
# lubricator WRITE hallo.adf TO ff1:
Read a disk to a file:
# lubricator READ hallo.adf FROM df0:
(Warning: Disk writing and reading starts immediately)
In addition to that, you can specify the VERBOSE option for more
information on network activity.
See also: Privacy concerns
7. Icon tooltypes
---------------------------------------------------------------------
Lubricator's configuration is stored in its icon tooltypes.
- 'STARTPAGE' - The home URL in the 'Index' facility.
- 'STARTFACILITY' - Name of the facility to start up with. For example
"local", "aminet", "pouet". Default: "index".
- 'DOWNLOADDIR' - Download directory in the 'Local' facility, default:
SYS:T
- 'DEVICE0', 'DEVICE1' - Devices for writing disk images, by default
df0: and df1:. It might be a good idea to assign a virtual floppy to the
second device, see for example fmsdisk.device from Aminet. RAD: works
too.
- 'CREATEICONS' - Create drawer icons for unpacked archives.
- 'NUMLINES' - Number of lines in the main list. Default: 12
- 'NOAGA' - Remove AGA-only releases from search results.
- 'BOOKMARK1' ... 'BOOKMARK9' - Bookmarks available through the
bookmarks menu.
- 'SEARCHPROXY' - Set the search proxy. The default search proxy handles
the facilities 'pouet' and 'aminet' (see below).
- 'DOWNLOADPROXY' - Set the download proxy.
- 'HTTPPROXY' - Set the HTTP proxy (rarely needed nowadays). Default:
none
- 'FACILITIES' - List of external search facilities, separated by
commas, default: "Pouët=pouet,Aminet".
For example, if you are interested in Aminet and games searches only,
you could specify "Aminet,Games".
A search facility is an arbitrary name sent to a search proxy as an
additional argument. Each facility can be preceded by an alias
(delimited by an equal sign), which will be shown in the GUI.
By default, searches are sent to SEARCHPROXY. In addition to that, each
facility can have its own specialized search proxy, by prefixing it with
the facility name, e.g. GAMESSEARCHPROXY, AMINETSEARCHPROXY, etc.
- 'MULTIVIEW' - An external program to display various files. Default:
"SYS:Utilities/Multiview". Kick 2.x users will need to find another
program, e.g. "viewer >NIL:" from aminet.net/text/show/viewer.lha.
- 'UNLHACMD' - Command for unpacking lha archives. Default: lha -aNq x
"%s" "%s/"
- 'UNZIPCMD' - Command for unpacking zip archives. Default: unzip -q -o
"%s" -d "%s/"
By default, unpacking produces an output window only in case of
problems. Check out the LhA and UnZip manuals to produce more verbose
output.
- 'OUTPUT' - Output window specification when starting external
programs. Default: "CON:20/20/600/140/Output/AUTO/CLOSE/WAIT"
8. Troubleshooting
---------------------------------------------------------------------
Q: The program doesn't start, in the shell it complains about
httpclient.library.
A: Delete the old version from AmiTCP:libs/httpclient.library.
Q: ZIP archives always seem to produce an output window, why?
A: Set the TZ env variable. See also 3. Installation, and timezone.doc
in the UnZip distribution.
9. Privacy concerns
---------------------------------------------------------------------
Privacy policy:
This software does not collect private data. If you use this program in
the default configuration, queries, results and downloads are roaming
the internet unencrypted between the search server and your Amiga.
Requests will be logged by the default server for debugging purposes,
and deleted automatically after one week or when the protocol grows too
large, whatever comes first.
Please note:
Http servers often redirect downloads to https - so you do not always
recognize by its URL if a download needs to be rerouted through the
download proxy.
If in doubt, you can create your own search and download server.
A. Server exchange protocol
---------------------------------------------------------------------
If you want to create your own proxy or download server, you need to
implement Lubricator's server exchange protocols. These have been kept
markedly simple.
Download:
GET <downloadserver>?url=<download>&token=lubricator
The download proxy can pass response headers to the client more or less
unmodified, but it should keep their number and size reasonably small.
Only the Content-* headers are really interesting. (Note: Future
versions of Lubricator and its default server might implement some token
negotiation scheme.)
Search:
GET <searchserver>?search=<query>&type=<facility>&format=lubricator
Additionally, the argument exclude=aga can be provided.
The search response is a list in ISO-8859-1 text. (Note: Future versions
of Lubricator and its search server might implement an encoding argument
for other ISO-8859 variants, such as ISO-8859-7.)
"key1": attr1="val1" attr2="val2" ...
"key2": attr3="val3" attr4="val4" ...
...
The key is the list's visual constituent, and relatively freeform. The
key length should not significantly exceed 50 characters. A fixed-width
font can be expected for display, and some limited ASCII art is
possible. Attribute names shouldn't be longer than 12 characters. For
escaping quotation marks inside names and values, use \", for the
backslash character, use \\.
Relevant attributes are URI and Type. URI can be absolute or relative.
Conventions for the Type keys:
"index" - Address, link to some other index
"download" - Some file, unspecified
"archive" - LhA or ZIP archive
"disk" - ADF disk image
"diskarchive" - DMS disk archive
"packdisk" - ADF disk image
Example line from an Aminet response:
" comm/net 68k NetFS-revised.lha": Short="Remote filesystem & AREXX
between Amigas" Arch="m68k-amigaos" Type="archive"
URI="http://aminet.net/comm/net/NetFS-revised.lha" Path="comm/net"
Size="620K" Date=""
Example line from a Pouët response:
"23 Fortocalypse by TEK ++++": Short="OCS demo by The Electronic Knights
2023-05-15" Date="2023-05-15" Kind="demo" Votes="66 ++++"
Filename="tek-fortocalypse" Type="download"
URI="http://archive.scene.org/pub/demos/groups/tek/tek-fortocalypse"
The first attribute (here, "Short") should contain as much additional
information as possible, as it is getting displayed witout user
interaction. Do not expect significantly more than 40 characters to be
displayed here.
Please keep the number of additional attributes and line lengths
reasonably small.
Use the command-line option VERBOSE to monitor request activity.
See also: Node.js proxy server examples
See also: 9. Privacy concerns
B. Changelog
---------------------------------------------------------------------
2.4 - some bugs fixed in URL decoding, processing of links, file
extension heuristics, and suggestion of savenames: Now treats .html in
URLs as links, all unknown extensions as downloads, href-only links (no
link text) are now shown, now converts URL-encoded filenames back to
normal
2.3 - Added READ argument for reading disks to files locally, requested
by Henne/AC; improved determination of local filenames from URLs; host
header did not provide port numbers, fixed in httpclient.library 4.3.
Node.js proxy server examples added.
2.2 - Unpacking of archives could hang during icon creation, fixed; did
not actually set the agent string to Lubricator, fixed with
httpclient.library 4.1
2.1 - Added command-line UNPACK feature; can now download and unpack to
a destination directory from command-line; command-line exits with WARN
if a destination file or unpack directory already exists; fixed \\ and
\" escaping in parser; reduced memory consumption for DMS unpacking;
fixed minor quirks in documentation generator; improved error reporting
and output in command-line disk writing; some cleanup in initialization
and exception handling; tries to no longer overwrite a drawer icon
provided by an archive
2.0 - Parser bits rewritten in assembler; Minor corrections in signal
handling, verbose output, improved documentation; AmigaGuide and
Installer added; some requests could be performed twice, corrected;
directories are now sorted to top in local facility; now deletes
__MACOSX garbage from archives automatically; version number bumped
1.9 - Improved documentation, Added OUTPUT tooltype, improved blocksize
calculation, detaches external viewer and executables started in
"Normal" mode, added SEARCH=SHOW command
1.8 - facilities now remember their list and address; now uses
fixed-width 'System Font' for the main list
1.7 - Added packdisk maker, STARTFACILITY, UNLHACMD, UNZIPCMD
1.6 - Added "Local" facility and browsing the download directory; now
avoids unnecessary sub directories when unarchiving; automatically shows
unarchived directories; smarter selection of directories and filenames
in file requesters; added external file viewing and MULTIVIEW tooltype;
improved dialogs for fewer clicks and more intuitive operation; Reload
on Aminet and Pouet facilities now lists the current releases; added
support for search proxies per facility; improved error reporting,
cleanup, many small quirks fixed
1.5 - Did not use the download proxy in command-line, corrected;
improved documentation; random demo suggestion did not select the
'pouet', but the first search facility, corrected; added double-click on
mainlist actions; added 'Accept' header, added Lubricator as User-Agent;
now requires httpclient.library v4
1.4 - Added FACILITIES
1.3 - Corrections in handling of the URL field; configurable search,
download and http proxies; when NOAGA is specified, caches are always
disabled when starting an executable, otherwise prompts user; "Suggest
Random Demos" improved; more meaningful error messages for connection
and proxy failures; more verbose executable disks
1.2 - Corrected handling of URI paths without trailing slashes;
dramatically improved compatibility when running executables, especially
from disk; running executables and making bootable disks from
executables with spaces in their filenames corrected; now correctly
reports disk errors on read/write/download disk images
1.0 - Improved documentation, some minor bugs fixed
0.93 - Added bookmarks menu; fixed possible illegal memory access during
tooltype parsing; improved filetype and html content detection; link
texts are now shortened if necessary; passing an URL in the command-line
works (again)
0.92 - Fixed crash when clicking 'Cancel' on unpacking DMS to disk;
reduced memory consumption; improved path handling, improved error
reporting; file downloads can be aborted
0.91 - Added Iconify function; added NUMLINES and NOAGA tooltypes,
removed NOASYNC tooltype
0.90 - Bugfix in devicename handling; reduced memory consumption;
cleanup
0.89 - Added 'suggest random demos' function; DMS unpacker in 'heavy'
mode slightly optimized in assembler
0.88 - Added CREATEICONS tooltype; DMS unpacker optimized in assembler a
bit; some fixes and cleanup
0.87 - DMS archives can now be unpacked directly from HTTP to disk,
without downloading before. httpclient.library updated to v3.0.
0.86 - Added a function to create a bootable disk for running an
executable
0.85 - The DMS unpacker is now integrated, faster, and requires less
memory. xdms and the PIPE: handler are no longer needed.
0.84 - Added support for downloading from https and ftp.
0.83 - Added async disk writing and NOASYNC tool type option.
0.82 - For known archives, the default action is now "Unarchive".
Progress displays no longer overwrite the link field, but are now shown
in the former Type field. Many minor bugs and quirks fixed.
0.81 - added support for writing ADF and DMS from menu and command-line.
0.80 - added unpacking lha, zip, and dms.
0.79 - added rudimentary HTML browsing capabilities.
0.73 - you can now enter an URL in the link field directly, too
0.72 - added VERBOSE option, fixed a crash in property management, link
field is now editable, allowing the user to change the link. Added
autorewrite to http in search proxy for scene.org servers
0.7 - added proxy support; added httpclient.library 2.1, which fixes
some proxy issues
0.6 - added device tooltypes, home button
0.5 - added some Pouët and Aminet search support
0.4 - added some command-line support, added icon, icon tooltype,
progress display, abort writing
0.3 - initial version
C. Licenses and Copyright
---------------------------------------------------------------------
MIT License
Copyright (c) 2021-2026 Timm S. Mueller
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Node.js proxy server examples kindly provided by Bodo Hinüber/Rabenauge.
Thanks!
xDMS - compiled into Lubricator
---------------------------------------------------------------------
Maintainer: Heikki Orsila
Author: Andre Rodrigues de la Rocha
xDMS is released as public domain software. You can spread it, modify it
and do anything with it without even asking first. But the author(s)
would like to know if you do something cool with it.
httpclient.library - HTTP client Amiga shared library
---------------------------------------------------------------------
Based on HTTPClient 1.1 by Eitan Michaelson
Completely rewritten as a drop-in-replacement for previously closed
source versions (up to 4.3) - probably fixed and added a few bugs along
the way.
HTTPClient's original MIT License is reproduced below:
Copyright (c) 2006 Eitan Michaelson
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
aminet net>