Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ephemera(1)		FreeBSD	General	Commands Manual		   ephemera(1)

     ephemera -- SCGI Blog Server

     ephemera [-f <config_file>	-m <max_conns> -u <user> -g <group> -i
	      <interface> -p <port> -l <socket>	-x]

     Ephemera is an event-driven SCGI application server dedicated to serving-
     up	a single blog with no comment facility.

     Ephemera is for people who	have their own hosts on	which they can install
     software, who know	HTML5 and CSS, and who prefer working with text-based
     tools. Posts are stored in	an in-memory SQLite database that is read from
     disk at startup.  Yes, Sunshine, you can afford to	keep the database in
     memory.  The complete works of Shakespeare	in plain text are less than 6

     You write your posts in HTML5.  You can put whatever elements you like
     into your posts, but the database stores only the HTML.  If you want to
     reference other resources,	you will need to create	web-visible directo-
     ries to hold those	resources.

     There is no web interface for managing content because I would rather be
     rolled in seal oil	and exposed to polar bears than	use web-based tools.
     You manage	the on-disk database with six munger(1)	scripts	that work with
     plain text.  Five are command-line	tools that can be used for one-off op-
     erations or shell scripting.  The sixth is	an interactive fullscreen
     database editor.  The scripts send	the server a SIGHUP to notify it to
     reload the	database.

     For example, you can add posts from remote	hosts like this:

     ssh user@host '/usr/local/bin/add.munger /path/to/db/ephemera.sqlite' < post.txt

     My	goodness.  That	is a prime candidate for a shell alias.

     The munger	scripts	are located in /usr/local/bin and are documented in-
     ternally with comments.  All scripts require the path to the database
     file to be	passed as a command line argument.

     Ephemera serves up	UTF-8 encoded web pages, but munger does not under-
     stand UTF-8.  This	means that you can use the munger scripts to manipu-
     late UTF-8	articles, but the motion and search commands in	edit.munger
     will move to the wrong locations on lines with multibyte characters.

     The five command-line scripts are named create.munger, add.munger,	re-
     place.munger, delete.munger, and extract.munger.

     The sixth script, edit.munger, is an interactive console program to view,
     add, delete, edit,	and search for posts in	the database.  The following
     commands are available.


     j		    Move the cursor up or down one line.  These	commands can
		    be preceded	with a repeat count.


     ]		    Move the cursor up or down one paragraph.  These commands
		    can	be preceded with a repeat count.


     [backspace]    Scroll the screen forward or backward one screenful.
		    These commands can be preceded with	a repeat count.


     G		    Move the cursor to the top or the bottom of	the current


     $		    Move the cursor to the start or end	of the current line.


     h		    Move the cursor forward or backward	by one character.
		    These commands can be preceded with	a repeat count.


     b		    Move the cursor forward or backward	by one word.  These
		    commands can be preceded with a repeat count.

     / <pattern>

     ? <pattern>    Search forward or backward in the current screen for a
		    match on a regular expression.  Searches wrap-around.
		    These commands can be preceded with	a repeat count.


     N		    Repeat the last pattern search in the same or the opposite
		    direction.	These commands can be preceded with a repeat

     q		    Quit the database editor.

     e		    Extract the	current	post to	a text file with the same name
		    as the post's database Id.

     s		    Search the database	using the SQLite full text search in-
		    terface.  Articles containing matches are added to the
		    post list in reverse chronological order.

     Control-l	    Load the post list with all	posts in reverse chronological

     i		    Toggle on or off the display of post Ids in	the post list.

     a		    Add	a new post to the database.  The editor	specifed by
		    the	EDITOR environment variable is run on an empty file.

		    Insert the post's complete title on	the first line.	 In-
		    sert a blank line after the	title line.  The title is
		    wrapped in an <h3> element when it is sent to clients.

		    Insert the post's body after the blank line.  Markup the
		    body to be proper HTML5.  Both the title and body are in-
		    serted into	a left-floated div.  If	you include block ele-
		    ments in your post bodies, then you	must make them float
		    left to render properly.  Alternately, you can set the
		    display property to	inline-block. This is true of ol, ul,
		    and	pre elements.

     d		    Delete the current post.

     [enter]	    Load the current post into the viewer.  When the viewer is
		    onscreen, the following additional commands	are available:

		    [enter]    Run the editor specified	by the EDITOR environ-
			       ment variable on	the current post.

		    u	       Update the database.  Do	this when you exit
			       from your editor	if you want to preserve	your

		    q	       Return to the post listing.

     If	it cannot allocate memory from the system, ephemera exits. You need to
     set the maximum number of simultaneous connections	with the -m option to
     a value that is suitable for your host's resources.

     To	configure ephemera:

     1.	  Set the server options in /etc/rc.conf appropriately for your	sys-

     2.	  copy /usr/local/share/ephemera/ephemera.config to the	location you
	  specify with the -f server option.  Edit the file.  Each setting is
	  documented with a comment.

     3.	  Configure your web server to forward requests	for the	resource you
	  have described with "path" in	ephemera.config	to the interface you
	  have described with "ephemera_flags" in /etc/rc.conf.

     4.	  Copy ephemera.css, Merriweather-Bold.ttf, Merriweather-BoldIt.ttf,
	  Merriweather-Light.ttf, and Merriweather-LightIt.ttf from /usr/lo-
	  cal/share/ephemera to	the directory that you specified with "web_di-
	  rectory" in ephemera.config.

     5.	  Start	your web server.  Start	ephemera with:

	  service ephemera start

	  Customize ephemera.css.

     The following command line	options	are available.	To use an option, in-
     sert it into the value of the ephemera_flags variable in /etc/rc.conf.
     For example,

     ephemera_flags="-u	www -g www -l /var/run/ephemera.socket"

     -f	 The -f	option specifies the path to the directory containing
	 ephemera.config.  This	value defaults to /usr/local/etc.

     -m	 The -m	option specifies the number of simultaneous connections	the
	 server	will accept.  The value	defaults to 8192.


     -g	 The -u	and the	-g options to specify the user and group of the	server
	 processes.  Both values default to "nobody".  If you use the -l op-
	 tion to make the server listen	on a UNIX socket, then you must	use
	 these options to ensure that ephemera runs with the same user or
	 group setting of the web server, or the webserver will	not be able to
	 connect to the	socket.

     -p	 The argument to the -p	option specifies the port to listen on.	 The
	 port defaults to 4000.

     -i	 By default, ephemera accepts connections on all interfaces it can
	 find capable of IPv4 or IPv6.	The -i option overrides	this behavior
	 to limit drood	to accepting connections from a	specified interface
	 only.	Pass the IP address of the desired interface as	argument.

     -l	 The -l	option specifies the path to a UNIX-domain socket for the
	 server	to listen on.  Use a UNIX socket instead of the	loopback in-
	 terface if the	web server and ephemera	run on the same	host.  Using
	 the loopback address unnecessarily interposes the TCP/IP stack	be-
	 tween the two servers,	which degrades performance.

	 The -l	option cannot be present on the	command	line if	the -p or -i
	 option	is also	present.  The server creates the socket	on startup.
	 The owner and group of	the socket is changed to the values of the -u
	 and -g	options.  The permissions of the socket	are set	to srwxrwx---.

     -x	 The -x	option prevents	ephemera from becoming a daemon.  The server
	 runs in the foreground	of the terminal	where it is started. The
	 server	is stopped with	signals	(ie., Control-C).

     James Bailie <>

				 June 19, 2021


Want to link to this manual page? Use this URL:

home | help