1 files changed, 110 insertions, 0 deletions

diff --git a/nfv-installer/script-installer/README b/nfv-installer/script-installer/README
new file mode 100644
index 0000000..e94e178
--- /dev/null
+++ b/nfv-installer/script-installer/README
@@ -0,0 +1,110 @@
+:The purpose of this installer is to guide you through creating a bootable
+Enea NFV Access installation on a physical media (e.g. USB stick or HDD).
+
+Prerequisites:
+    - A GRUB .efi binary
+    - A drive of 16GB or larger
+    - For USB booting you will need:
+        - A development based rootfs (e.g. enea-nfv-access-dev-inteld1521.tar.gz)
+    - For booting from an SSD or HDD you will need:
+        - Any rootfs that needs to be installed on the board
+          (e.g. enea-nfv-access.tar.gz)
+
+A bootable media is created after the installer runs the following steps:
+    1. Create two partitions on a designated drive (e.g. /dev/sda):
+       - a 512MB partition for GRUB
+       - the rest of the drive is reserved for the rootfs.
+    2. Configure GRUB on one partition (usually the first one).
+    3. Copy a root filesystem on the other partition.
+
+Note: Running step 3 will implicitly copy the installer on that root filesystem
+in /usr/bin/install_nfvaccess.sh
+----------------------------------------------------------------------------------------
+To get a list of what commands are built in the installer, launch it with root
+rights and press ENTER, once the "nfv_installer>" console is displayed:
+    help              - a guide on how to use the installer
+    list-params       - lists parameters
+    list-steps        - lists the available steps and the parameters that they depend on
+    set               - sets a parameter (e.g. "set drive=/dev/sda")
+    clear             - clears a parameter (e.g. "clear drive")
+    list-partitions   - lists current drives and partitions
+    dry               - describes the steps to be executed and checks if the files exist
+    run               - executes the steps
+    q or quit         - exits the script
+
+Run 'list-steps' to understand the built-in steps that the installer
+can execute and what parameters they depend on in order to be executed.
+
+Running 'list-steps' will print the following:
+    1. Format drive - Uses the drive set for the "drive" parameter to create a
+    512MB partition for GRUB and another partition for the rootfs. The rootfs
+    partition will be as large as the physical media minus 512MB.
+        Depends on the following parameter(s):
+            drive=
+    2. GRUB install - Installs the binary pointed by "grub_binary" on the drive
+    set in "grub_destination". A grub.cfg file will be created that will be
+    configured to boot off of "rootfs_destination".
+        Depends on the following parameters:
+            grub_destination=
+            grub_binary=
+            rootfs_destination=
+    3. Root filesystem install - Copies the files found in "rootfs_targz" to
+    the drive set in "rootfs_destination".
+        Depends on the following parameters:
+            rootfs_targz=
+            rootfs_destination=
+
+A parameter can be set through the "set" command or cleared through "clear".
+As some parameters are common for multiple steps, like rootfs_destination
+is for the GRUB and rootfs installation steps, you can get a list of all the
+parameters, by running "list-params".
+
+The following parameters can be configured:
+    grub_destination=[drive]    - specifies the drive where GRUB will be
+                                  installed
+    grub_binary=[file]          - points to the GRUB executable to be installed
+                                  where grub_destination is set
+    rootfs_destination=[drive]  - specifies where the rootfs will be deployed
+    rootfs_targz=[.tar.gz file] - what file to unpack to where
+                                  rootfs_destination is set
+    drive=[/dev/sdaX]            - what drive to partition
+
+Before running the actual partitioning and copying, a dry run can be executed
+without affecting the actual layout of the physical media, by running the
+"dry" command.
+
+Example of partitioning a drive:
+    set drive=/dev/sda
+    run
+
+Example of partitioning a drive, installing GRUB and a root filesystem:
+    set drive=/dev/sda
+    set grub_destination=/dev/sda1
+    set grub_binary=/home/user/grub-binary.efi
+    set rootfs_destination=/dev/sda2
+    set rootfs_targz=/home/user/rootfs.tar.gz
+    run
+
+Example of deploying ONLY a root filesystem:
+    set rootfs_destination=/dev/sda2
+    set rootfs_targz=/home/user/rootfs.tar.gz
+    runs
+
+Troubleshooting:
+    - GRUB is throwing "error: no such partition" or "error: disk not found":
+    The default GRUB config is set to use 'hd0' as the primary drive for
+    booting.
+    Due to this, the errors described above have two possible causes:
+        - The drive where NFV Access was installed is not identified as 'hd0'
+        by the BIOS
+        - The BIOS has assigned the 'hd0' label to a different drive (e.g. USB
+        stick) than the one where NFV Access was installed.
+    Solution:
+        1. In the GRUB selection screen press 'c' to enter the command line.
+        2. Run 'ls' to list all the available partitions.
+        3. For each available partition run 'ls PARTITION' in order to identify
+        where NFV Access was installed.
+        4. After identifying the partition, press ESC to return to the GRUB
+        selection screen and press 'e' to edit the boot command.
+        5. Set the boot partition to the one identified in step 3
+        6. Press F10 to boot