eja is a versatile command-line tool primarily designed as a lightweight web server for static and dynamic content. It also functions as a text scanner utility (similar to awk but using Lua patterns) and a standalone Lua 5.2 interpreter with extended functionalities baked in.
Originally available for Debian/Linux, eja has now been updated and ported to other Unix-like operating systems, including macOS (Darwin). It achieves its functionality through a combination of C code for core system interactions (such as process management, sockets, and file system operations) and a rich set of embedded Lua libraries for higher-level tasks.
- Micro Web Server:
- Serves static files.
- Handles dynamic content through
.luaor pre-compiled.ejascripts. - Configurable host, port, web root path, and buffer size.
- Optional directory listing.
- Background daemon mode (
--web-start,--web-stop). - Simple time-based hash authentication mechanism (
ejaWebAuth). - User management helper (
--web-user).
- Text Scanner:
- Processes text streams (stdin or file) line by line or based on custom record separators.
- Uses Lua patterns for field separation (default:
%S+). - Executes Lua scripts for each record, providing the full row (
R) and matched fields (F).
- Lua Interpreter:
- Runs Lua 5.2 scripts.
- Includes an interactive shell (
--shell). - Can execute
.ejaportable bytecode files. - Exports Lua scripts to
.ejabytecode (--export).
- Extended Functionality (via C bindings & embedded Lua libs):
- System Interaction: Process creation, killing, sleeping (fork, kill, sleep), PID retrieval, cleaning up child processes, file stats (stat), directory listing and creation.
- Networking: Low-level TCP/UDP socket operations (create, bind, connect, listen, accept, read, write, options), DNS lookups (getaddrinfo). Includes helper functions for HTTP GET/POST (ejaWebGet, ejaJsonPost).
- Simple Database: File-based key-value store (
ejaDb*functions). - Data Handling: JSON encoding/decoding, Base64 encoding/decoding, struct packing/unpacking.
- Encryption & Hashing: AES encryption/decryption, SHA1, SHA256.
- MariaDB/MySQL Client: Embedded client for database interactions.
- Utilities: MIME type detection, TAR file extraction, logging framework, table manipulation helpers, string formatting.
- Library Management: Simple update/install/remove mechanism for
.ejalibraries (--update,--install,--remove). - System Setup: Helper command (
--setup) to create default directories and configuration files (including a basic systemd service file).
- Clone the repository:
git clone https://github.com/eja/eja.git cd eja - Compile:
For a statically linked binary (if supported by your toolchain):
make
make static
- Install (optional):
By default, this installs to
/usr/local. You might needsudo.This will install thesudo make install
ejabinary to/usr/local/binand the man page to/usr/local/share/man/man1.
The basic syntax is:
eja [SCRIPT] [OPTION]...For a full list of options, see the man page:
man ejaOr display help in the terminal:
eja --help # Basic help
eja --help full # Full help including library options-
Run a Lua script:
eja myscript.lua
-
Run an eja bytecode script:
eja mybytecode.eja
-
Use as a text scanner:
print second word of each line:
cat somefile.txt | eja --scan 'print(F[2])'
print lines matching "ERROR":
cat somefile.txt | eja --scan "/ERROR/"
-
Start the interactive Lua shell:
eja --shell
-
Export a Lua script to bytecode:
eja --export myscript.lua --export-name mybytecode # Creates mybytecode.eja -
Update eja or an eja library:
eja --update # Updates eja itself eja --update mylibrary # Updates mylibrary.eja from update.eja.it or GitHub
eja makes it simple to run a local web server for various purposes.
1. Directory Listing:
To quickly share or browse files in a directory via HTTP, enable directory listing:
# Navigate to the directory you want to serve
cd ~/my_shared_files
# Start eja, enabling directory listing on the default port (35248)
eja --webNow, open your web browser and go to http://localhost:35248. You will see a list of files and subdirectories within ~/my_shared_files. Clicking a file will download it, and clicking a directory will navigate into it.
2. Static HTML/Website Testing:
If you are developing a simple website (HTML, CSS, JavaScript, images), you can use eja as a local test server:
# Assume your website files are in ~/projects/my_website
# with index.html at the root
cd ~/projects/my_website
# Start eja in the project directory
eja --web --web-port 8000 # Use port 8000 instead of the default- Access the site at
http://localhost:8000. ejawill automatically serveindex.htmlif it exists in the current directory (~/projects/my_website).- It will also serve other files like
style.cssif your HTML references them with relative paths (e.g.,<link rel="stylesheet" href="style.css">).
3. Dynamic Content (Simple URL Sum):
eja can execute Lua scripts (.lua or compiled .eja) to generate dynamic responses. The script receives a web object containing request details and can modify it to set the response.
-
Create the script (
sum.lua): Save the following code in a file namedsum.lua:-- sum.lua -- The 'web' object is implicitly passed as the first argument web = ... -- Get query parameters 'a' and 'b' from the URL -- web.opt contains decoded query parameters local a = tonumber(web.opt.a) or 0 local b = tonumber(web.opt.b) or 0 local result = a + b -- Set the response content type and data web.headerOut['Content-Type'] = 'text/plain' web.data = string.format("The sum of %s and %s is: %s", a, b, result) -- No need to explicitly return the web object, modifying it is sufficient.
-
Run the server: Navigate to the directory containing
sum.luaand starteja:cd /path/to/directory/containing/script eja --web -
Access the dynamic endpoint: Open your browser or use
curl:curl "http://localhost:35248/sum.lua?a=15&b=27"This will output:
The sum of 15 and 27 is: 42You can change the values of
aandbin the URL to get different results. If parameters are missing, they default to 0.
4. Daemon Control:
- Start the web server as a background daemon (using defaults or config):
eja --web-start
- Stop the web server running on the default port (35248):
eja --web-stop
- Stop the web server running on port 8080:
eja --web-stop 8080
- Compile-time Paths: Default paths for libraries, configuration, logs, etc., can be set during compilation via CFLAGS in the
Makefile(e.g.,make CFLAGS="-DEJA_PATH_ETC=/etc/eja" install). - Runtime Configuration: The
--initoption loads/etc/eja/eja.init(by default). This Lua file can seteja.optvalues to configure behavior, commonly used for the daemon started via--web-startor a system service. - System Setup: The
eja --setupcommand helps create default directories (/var/eja/web,/var/lock,/tmp, etc.) and a basic/etc/eja/eja.initfile, along with a sample systemd service unit.