Skip to content

Commit

Permalink
added man page, reworked README, and more
Browse files Browse the repository at this point in the history
  • Loading branch information
@arcmags
arcmags committed Nov 8, 2017
1 parent 35b7579 commit 7f59ae8
Show file tree
Hide file tree
Showing 5 changed files with 222 additions and 157 deletions.
98 changes: 52 additions & 46 deletions README.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -569,76 +569,82 @@ <h1>Installation</h1>
ramroot script can also be run directly from a local git clone of this
repository.</p>
</div>
<div class="section" id="usage">
<h1>Usage</h1>
<div class="section" id="synopsis">
<h1>Synopsis</h1>
<p><tt class="docutils literal">ramroot &lt;action&gt; [options]</tt></p>
</div>
<div class="section" id="description">
<h1>Description</h1>
<p>Ramroot can enable and disable the pre-userspace loading of the root
(and <em>/boot</em>, if it exists) filesystem to RAM during system boot.</p>
<p>When ramroot is enabled, during the initial phase of boot the amount
of detected RAM on the computer along with the size the root filesystem
to be copied is shown on the screen. If there is at least 500MB
more RAM than the size of the filesystem, the user will be prompted
to load the root filesystem to RAM.
(Confirmation prompt defaults to yes with a 15 second timeout.)</p>
<p>The size of the zram partition created is determined by taking the
size of the root filesystem plus half of the extra available RAM
(to a maximum of 6GB).</p>
</div>
<div class="section" id="actions">
<h1>Actions</h1>
<p>Action performed by ramroot; one must be specified.</p>
<dl class="docutils">
<dt><tt class="docutils literal">ramroot [options]</tt></dt>
<dd>All actions are invoked with the <em>ramroot</em> script. At least one option
of either <em>--enable</em>, <em>--disable</em>, or <em>--remove</em> must be specified.</dd>
<dt><tt class="docutils literal">disable, <span class="pre">--disable,</span> <span class="pre">-D</span></tt></dt>
<dd>Remove ramroot from <em>/etc/mkinitcpio.conf</em> HOOKS.
Remove ext4 and zram from <em>/etc/mkinitcpio.conf</em> MODULES.
Rebuild linux cpio boot image.</dd>
<dt><tt class="docutils literal">enable, <span class="pre">--enable,</span> <span class="pre">-E</span></tt></dt>
<dd>Rebuild build and runtime hooks in /usr/lib/initcpio.
Add ramroot to <em>/etc/mkinitcpio.conf</em> HOOKS.
Add ext4 and zram to <em>/etc/mkinitcpio.conf</em> MODULES.
Rebuild linux cpio boot image.</dd>
<dt><tt class="docutils literal">remove, <span class="pre">--remove,</span> <span class="pre">-R</span></tt></dt>
<dd>Disable ramroot.
Remove build and runtime hooks from <em>/usr/lib/initcpio</em>.</dd>
</dl>
</div>
<div class="section" id="options">
<h1>Options</h1>
<p>All options are optional (although <em>--root</em> may be required in rare cases).</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">-b,</span> <span class="pre">--boot</span> [UUID]</tt></dt>
<dd>Specify the <em>/boot</em> UUID to use when building hooks; necessary if
unable to detect UUID via <em>lsblk</em> or <em>/etc/fstab</em>.</dd>
<dt><tt class="docutils literal"><span class="pre">-D,</span> <span class="pre">--disable</span></tt></dt>
<dd>Disable ramroot. Remove ramroot HOOK and required MODULES from
<em>/etc/mkinitcpio.conf</em> and rebuild linux cpio boot image.</dd>
<dt><tt class="docutils literal"><span class="pre">-E,</span> <span class="pre">--enable</span></tt></dt>
<dd>Enable ramroot. Rebuild build and runtime hooks and place in
<em>/usr/lib/initcpio</em>. Add ramroot HOOK and required MODULES to
<em>/etc/mkinitcpio.conf</em> and rebuild linux cpio boot image.</dd>
<dt><tt class="docutils literal"><span class="pre">-H,</span> <span class="pre">--help</span></tt></dt>
<dd>Display help text and exit.</dd>
<dt><tt class="docutils literal"><span class="pre">-K,</span> <span class="pre">--keep</span></tt></dt>
<dd>Keep copies of new build and runtime hooks in <em>~/.cache/ramroot</em>.</dd>
<dt><tt class="docutils literal"><span class="pre">-r,</span> <span class="pre">--root</span> [UUID]</tt></dt>
<dd>Specify the root UUID to use when building hooks; necessary if
unable to detect UUID via lsblk or <em>/etc/fstab</em>.</dd>
<dt><tt class="docutils literal"><span class="pre">-R,</span> <span class="pre">--remove</span></tt></dt>
<dd>Disable ramroot and remove build and runtime hooks from
<em>/usr/lib/initcpio</em>.</dd>
</dl>
</div>
<div class="section" id="operation">
<h1>Operation</h1>
<p>If ramroot is enabled, during the initial phase of the boot process,
the amount of available RAM on the computer along with the size of the
root filesystem to be copied is detected and shown on the screen. If the
available RAM is at least 500MB more than the data contained on the root
filesystem, the user will be prompted to load the root filesystem to RAM.
(Confirmation prompt defaults to <em>yes</em> with a 15 second timeout.)</p>
<p>The size of the zram partition created is determined by taking the size of
the root filesystem plus half of the extra available RAM to a maximum of 6GB.</p>
<p>The filesystem transfer to RAM can take several minutes. As soon as the boot
process is complete, the USB device (or whatever boot device) can be removed.</p>
<div class="section" id="notes">
<h1>NOTES</h1>
<p>The filesystem transfer to RAM can take several minutes. As soon as
the boot process is complete, the boot media can be safely removed.</p>
<p>Remember that all changes to files in RAM are completely lost once the
computer is shutdown. To update the system and edit files, boot the device
without transferring the filesystem to RAM.</p>
</div>
<div class="section" id="tips">
<h1>Tips</h1>
computer is reboot. To update the system and edit files, boot the
device without transferring the filesystem to RAM.</p>
<p>Keep a clean and trimmed down system to maintain faster RAM sync times.
Arch Linux stores downloaded packages in <em>/var/cache/pacman/pkg/</em>. After
every update, if no problems occur, consider removing <a class="reference external" href="https://wiki.archlinux.org/index.php/pacman#Cleaning_the_package_cache">old packages</a>.
Execute <tt class="docutils literal">pacman <span class="pre">-Sc</span></tt> to remove all packages that aren't currently installed.
Execute <tt class="docutils literal">paccache <span class="pre">-rk0</span></tt> to remove all packages.</p>
<p>From experience: higher quality (more expensive) USB flash drives
often exhibit a huge improvement in sync times.</p>
Consider installer fewer packages if you indend on loading to RAM often.</p>
<p>Also know that higher quality (more expensive) USB flash drives
often exhibit a huge improvement in RAM sync times.</p>
</div>
<div class="section" id="issues-ideas-to-implement-maybe">
<h1>Issues / Ideas to implement (maybe)</h1>
<div class="section" id="issues-future-implementations">
<h1>Issues / Future Implementations</h1>
<ul class="simple">
<li>add a ramroot-flush function to sync the RAM filesystem back to the
initial boot device (simple)</li>
<li>test on other distros</li>
<li><em>status</em> action</li>
<li><em>--rsync</em> option (maybe use rsync automatically if installed)</li>
<li>test with full disk encryption</li>
<li><em>flush</em> action to sync the RAM filesystem back to the
initial boot device</li>
<li>add support for other partitions users may have</li>
<li><em>--status</em> option</li>
<li><em>--rsync</em> option (or maybe use rsync automatically if installed)</li>
<li><em>--incognito</em> mode?</li>
<li>enable on first install?</li>
<li>test on other distros</li>
</ul>
</div>
<div class="section" id="credits">
Expand All @@ -651,7 +657,7 @@ <h1>Credits</h1>
<tbody valign="top">
<tr class="field"><th class="field-name">Author:</th><td class="field-body">Chris Magyar</td>
</tr>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1.1</td>
<tr class="field"><th class="field-name">Version:</th><td class="field-body">1.1.2</td>
</tr>
<tr class="field"><th class="field-name">License:</th><td class="field-body">GPL 3.0</td>
</tr>
Expand Down
116 changes: 63 additions & 53 deletions README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,30 +31,61 @@ ramroot script can also be run directly from a local git clone of this
repository.


Usage
=====
Synopsis
========

``ramroot <action> [options]``


Description
===========

Ramroot can enable and disable the pre-userspace loading of the root
(and */boot*, if it exists) filesystem to RAM during system boot.

When ramroot is enabled, during the initial phase of boot the amount
of detected RAM on the computer along with the size the root filesystem
to be copied is shown on the screen. If there is at least 500MB
more RAM than the size of the filesystem, the user will be prompted
to load the root filesystem to RAM.
(Confirmation prompt defaults to yes with a 15 second timeout.)

The size of the zram partition created is determined by taking the
size of the root filesystem plus half of the extra available RAM
(to a maximum of 6GB).


Actions
=======

Action performed by ramroot; one must be specified.


``disable, --disable, -D``
Remove ramroot from */etc/mkinitcpio.conf* HOOKS.
Remove ext4 and zram from */etc/mkinitcpio.conf* MODULES.
Rebuild linux cpio boot image.

``enable, --enable, -E``
Rebuild build and runtime hooks in /usr/lib/initcpio.
Add ramroot to */etc/mkinitcpio.conf* HOOKS.
Add ext4 and zram to */etc/mkinitcpio.conf* MODULES.
Rebuild linux cpio boot image.

``ramroot [options]``
All actions are invoked with the *ramroot* script. At least one option
of either *--enable*, *--disable*, or *--remove* must be specified.
``remove, --remove, -R``
Disable ramroot.
Remove build and runtime hooks from */usr/lib/initcpio*.


Options
=======

All options are optional (although *--root* may be required in rare cases).

``-b, --boot [UUID]``
Specify the */boot* UUID to use when building hooks; necessary if
unable to detect UUID via *lsblk* or */etc/fstab*.

``-D, --disable``
Disable ramroot. Remove ramroot HOOK and required MODULES from
*/etc/mkinitcpio.conf* and rebuild linux cpio boot image.

``-E, --enable``
Enable ramroot. Rebuild build and runtime hooks and place in
*/usr/lib/initcpio*. Add ramroot HOOK and required MODULES to
*/etc/mkinitcpio.conf* and rebuild linux cpio boot image.

``-H, --help``
Display help text and exit.

Expand All @@ -65,62 +96,41 @@ Options
Specify the root UUID to use when building hooks; necessary if
unable to detect UUID via lsblk or */etc/fstab*.

``-R, --remove``
Disable ramroot and remove build and runtime hooks from
*/usr/lib/initcpio*.


Operation
=========

If ramroot is enabled, during the initial phase of the boot process,
the amount of available RAM on the computer along with the size of the
root filesystem to be copied is detected and shown on the screen. If the
available RAM is at least 500MB more than the data contained on the root
filesystem, the user will be prompted to load the root filesystem to RAM.
(Confirmation prompt defaults to *yes* with a 15 second timeout.)

The size of the zram partition created is determined by taking the size of
the root filesystem plus half of the extra available RAM to a maximum of 6GB.
NOTES
=====

The filesystem transfer to RAM can take several minutes. As soon as the boot
process is complete, the USB device (or whatever boot device) can be removed.
The filesystem transfer to RAM can take several minutes. As soon as
the boot process is complete, the boot media can be safely removed.

Remember that all changes to files in RAM are completely lost once the
computer is shutdown. To update the system and edit files, boot the device
without transferring the filesystem to RAM.


Tips
====
computer is reboot. To update the system and edit files, boot the
device without transferring the filesystem to RAM.

Keep a clean and trimmed down system to maintain faster RAM sync times.
Arch Linux stores downloaded packages in */var/cache/pacman/pkg/*. After
every update, if no problems occur, consider removing `old packages`_.
Execute ``pacman -Sc`` to remove all packages that aren't currently installed.
Execute ``paccache -rk0`` to remove all packages.
Consider installer fewer packages if you indend on loading to RAM often.

From experience: higher quality (more expensive) USB flash drives
often exhibit a huge improvement in sync times.
Also know that higher quality (more expensive) USB flash drives
often exhibit a huge improvement in RAM sync times.


Issues / Ideas to implement (maybe)
Issues / Future Implementations
===================================

* add a ramroot-flush function to sync the RAM filesystem back to the
initial boot device (simple)
* *status* action

* test on other distros
* *--rsync* option (maybe use rsync automatically if installed)

* add support for other partitions users may have
* test with full disk encryption

* *--status* option
* *flush* action to sync the RAM filesystem back to the
initial boot device

* *--rsync* option (or maybe use rsync automatically if installed)

* *--incognito* mode?
* add support for other partitions users may have

* enable on first install?
* test on other distros


Credits
Expand All @@ -133,7 +143,7 @@ by several inquisitive `forum posts`_.
Chris Magyar

:Version:
1.1.1
1.1.2

:License:
GPL 3.0
Expand Down
78 changes: 78 additions & 0 deletions lib/man/ramroot.8
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,78 @@
.TH RAMROOT 8 "November 2017" "ramroot 1.1.2" "Ramroot Manual"
.SH NAME
ramroot \- load root filesystem entirely to RAM during boot
.SH SYNOPSIS
.B ramroot
<\fIACTION\fR> [\fIOPTIONS\fR]
.SH DESCRIPTION
\fIRamroot\fR can enable and disable the pre\-userspace loading of the
root (and /boot, if it exists) filesystem to RAM during system boot.
.PP
When \fIramroot\fR is enabled, during the initial phase of boot
the amount of detected RAM on the computer along with the size the
root filesystem to be copied is shown on the screen. If there is at
least 500MB more RAM than the size of the filesystem, the user will
be prompted to load the root filesystem to RAM.
(Confirmation prompt defaults to yes with a 15 second timeout.)
.PP
The size of the \fIzram\fR partition created is determined by taking
the size of the root filesystem plus half of the extra available
RAM (to a maximum of 6GB).
.SH ACTIONS
Action performed by ramroot; one must be specified.
.PP
.TP
\fBdisable\fR, \fB\-\-disable\fR, \fB\-D\fR
Remove \fIramroot\fR from /etc/mkinitcpio.conf HOOKS.
Remove \fIext4\fR and \fIzram\fR from /etc/mkinitcpio.conf MODULES.
Rebuild linux cpio boot image.
.TP
\fBenable\fR, \fB\-\-enable\fR, \fB\-E\fR
Rebuild build and runtime hooks in /usr/lib/initcpio.
Add \fIramroot\fR to /etc/mkinitcpio.conf HOOKS.
Add \fIext4\fR and \fIzram\fR to /etc/mkinitcpio.conf MODULES.
Rebuild linux cpio boot image.
.TP
\fBremove\fR, \fB\-\-remove\fR, \fB\-R\fR
Disable ramroot. Remove build and runtime hooks from
/usr/lib/initcpio.
.SH OPTIONS
All options are optional (although \fB--root\fR may need to be used in rare
cases).
.PP
.TP
\fB\-b\fR, \fB\-\-boot\fR \fIUUID\fR
Specify the /boot UUID to use when building hooks; necessary if
unable to detect UUID via lsblk or /etc/fstab.
.TP
\fB\-H\fR, \fB\-\-help\fR
Display help text and exit.
.TP
\fB\-K\fR, \fB\-\-keep\fR
Keep copies of new build and runtime hooks in ~/.cache/ramroot.
.TP
\fB\-r\fR, \fB\-\-root\fR \fIUUID\fR
Specify the root UUID to use when building hooks; necessary if
unable to detect UUID via lsblk or /etc/fstab.
.SH NOTES
The filesystem transfer to RAM can take several minutes. As soon as
the boot process is complete, the boot media can be safely removed.
.PP
All changes to files in RAM are completely lost once the
computer is reboot. To update the system and edit files, boot
the device without transferring the filesystem to RAM.
.PP
Keep a clean and trimmed down system to maintain faster RAM sync times.
Remove old packages and cached files after system
upgrades to keep the size of the root filesystem down.
Consider installing fewer packages if you intend on loading
to RAM often.
.SH AUTHOR
Written by Chris Magyar.
.SH COPYRIGHT
Copyright \(co 2017 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.SH "SEE ALSO"
Official ramroot source: <https://github.com/arcmags/ramroot/>
Loading

0 comments on commit 7f59ae8

Please sign in to comment.