From: Nikos Skalkotos Date: Tue, 22 Jan 2013 15:20:37 +0000 (+0200) Subject: Update the documentation X-Git-Tag: v0.2.2~1 X-Git-Url: https://code.grnet.gr/git/snf-image-creator/commitdiff_plain/5aa252409f4cbff412a7be2a7a4629b8f0812134 Update the documentation * Add contact info * Add info on how to install Arch Linux packages * Add limitations section in usage --- diff --git a/docs/index.rst b/docs/index.rst index a27ad0f..e9a4e3d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,11 +17,19 @@ Contents: install usage +Contact +======= -Indices and tables -================== +For questions or bug reports you can contact the Synnefo team at the following +mailing lists: -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + * Users list: synnefo@googlegroups.com + * Developers list: synnefo-devel@googlegroups.com + +.. + Indices and tables + ================== + * :ref:`genindex` + * :ref:`modindex` + * :ref:`search` diff --git a/docs/install.rst b/docs/install.rst index 9cf0e6b..36afaa2 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -25,15 +25,18 @@ snf-image-creator depends on the following programs: The above dependencies are resolved differently, depending on the installation method you choose. There are two installation methods available: -#. `Installation using official packages <#install-snf-image-creator-using-official-packages>`_ (currently only for Ubuntu 12.04 LTS and 12.10). +#. `Installation using packages <#install-snf-image-creator-using-packages>`_ (currently only for Ubuntu and Arch Linux). #. `Installation from source <#install-snf-image-creator-from-source>`_ -Install snf-image-creator using official packages -================================================= +Install snf-image-creator using packages +======================================== -For Ubuntu systems, you can use our official packages found in *grnet/synnefo* -Lauchpad PPA. +Ubuntu +------ + +For *Ubuntu 12.04 LTS* and *12.10* systems, you can use our official packages +found in *grnet/synnefo* Lauchpad PPA. Add the synnefo PPA in your system: @@ -71,6 +74,50 @@ If you are using Ubuntu 12.10, also install libguestfs-tools: If you are asked during the installation to create/update a "supermin appliance", choose "Yes". +.. warning:: + In *Ubuntu 12.10* the current package of libguestfs (1.18-2) is broken. Take + a look at the open `bug report `_. + Until version 1.18-2ubunut1 is out, you may workaround this problem by + creating a symlink like this: + + *sudo ln -s /usr/lib/guestfs /usr/lib/x86_64-linux-gnu/guestfs* + +Arch Linux +---------- + +For *Arch Linux* there are **unofficial** packages in AUR: +https://aur.archlinux.org/packages/snf-image-creator/ kindly provided by +Axilleas Pipinellis . + +.. note:: + Those packages are not maintained by the Synnefo development team. + + Please direct package-specific questions to Axilleas Pipinellis , + Cc: the Synnefo development team + +To install the package you may use *yaourt*. Create and install +the *yaourt* package: + +.. code-block:: console + + $ wget https://aur.archlinux.org/packages/pa/package-query/package-query.tar.gz + $ tar -xvf package-query.tar.gz + $ cd package-query + $ makepkg -s + $ pacman -U package-query--.pkg.tar.xz + $ cd .. + $ wget https://aur.archlinux.org/packages/ya/yaourt/yaourt.tar.gz + $ tar -xvf yaourt.tar.gz + $ cd yaourt + $ makepkg -s + $ pacman -U yaourt--.pkg.tar.xz + +Install *snf-image-creator* using yaourt: + +.. code-block:: console + + $ yaourt -Sa snf-image-creator + Install snf-image-creator from source ===================================== diff --git a/docs/usage.rst b/docs/usage.rst index ce8c99d..2b6971b 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -217,7 +217,7 @@ system that runs the program. This is done either by specifying / as input media or by using the *Bundle Host* button in the media selection dialog of snf-mkimage. During this operation, the files of the disk are copied into a temporary image file, which means that the file system that will host the -temporary image needs to have a lot of free space (see `the tmpdir option`_ +temporary image needs to have a lot of free space (see `large temporary files`_ for more information). Creating a new image @@ -281,8 +281,22 @@ confirm the provided data. Choosing *YES* will create and upload the image to your *~okeanos* account. -Some caveats on image creation -============================== +Limitations +=========== + +Supported operating systems +--------------------------- + +*snf-image-creator* can only fully function on input media hosting *Linux* +systems. The program will detect the needed metadata and you may use it to +upload and register other *Unix* or *Windows* images, but you cannot use it to +shrink them or perform system preparation operations. + +Logical Volumes +--------------- + +The program cannot work on LVM partitions [#f1]_. The input media may only +contain primary or logical partitions. Para-virtualized drivers ------------------------ @@ -298,13 +312,16 @@ the VM won't be able to boot. Many popular Linux distributions, like Ubuntu and Debian, will automatically create a generic initial ramdisk file that contains many different modules, including the VirtIO drivers. Others that target more experienced users, like -Slackware, won't do that [#f1]_. *snf-image-creator* cannot resolve this kind +Slackware, won't do that [#f2]_. *snf-image-creator* cannot resolve this kind of problems and it's left to the user to do so. Please refer to your distribution's documentation for more information on this. You can always check if a system can boot with para-virtualized disk controller by launching it with kvm using the *if=virtio* option (see the kvm command in the `Creating a new image`_ section). +Some caveats on image creation +============================== + Image partition schemes and shrinking ------------------------------------- @@ -322,8 +339,8 @@ Keep this in mind when creating images. It's always better to have your swap partition placed as the last partition on the disk and have your largest partition (*/* or */home*) just before that. -The tmpdir option ------------------ +Large temporary files +--------------------- *snf-image-creator* may create large temporary files when running: @@ -343,4 +360,5 @@ supported by both *snf-image-creator* and *snf-mkimage*. .. rubric:: Footnotes -.. [#f1] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd +.. [#f1] http://sourceware.org/lvm2/ +.. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd