IF YOU WOULD LIKE TO GET AN ACCOUNT, please write an email to s dot adaszewski at gmail dot com. User accounts are meant only to report issues and/or generate pull requests. This is a purpose-specific Git hosting for ADARED projects. Thank you for your understanding!
No puede seleccionar más de 25 temas Los temas deben comenzar con una letra o número, pueden incluir guiones ('-') y pueden tener hasta 35 caracteres de largo.

Basic_Usage_Guide.md 4.7KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135
  1. # Focker Basic Usage Guide
  2. ## Prerequisites
  3. In order to get started, you have to prepare a base image for usage with Focker.
  4. In order to do so, you can use the `focker bootstrap` command.
  5. `focker bootstrap` has the following syntax:
  6. ```
  7. usage: focker.py bootstrap [-h] [--tags TAGS [TAGS ...]] [--empty]
  8. optional arguments:
  9. -h, --help show this help message and exit
  10. --tags TAGS [TAGS ...], -t TAGS [TAGS ...]
  11. --empty, -e
  12. ```
  13. If you use the `--empty` switch, it will create an empty image. This is used
  14. principally for testing and unless you want to set up your image manually, it is
  15. recommended to run `bootstrap` without the `--empty` switch.
  16. The `--tags` parameter lets you specify the tags that the resulting image will
  17. receive. If you do not specify this, the image will be tagged with `freebsd-latest`
  18. and `freebsd-x.y` where `x.y` will be the major and minor version obtained
  19. from a call to `freebsd-version`.
  20. The `bootstrap` command creates a new image and runs `bsdinstall jail` targeting
  21. its mountpoint. It is recommended to install only the base system (no ports, no lib32),
  22. disable all services and do not add any users. The base image will most likely serve as
  23. the starting point for all the other images that you will be building. Pre-made
  24. `Fockerfile` recipes, unless indicated otherwise, will most likely expect a
  25. barebones image as the base.
  26. It is a good practice to account for a base image that has been created by just
  27. clicking through the `bsdinstall jail` installer. Therefore, many `Fockerfile`
  28. recipes will execute the following steps to disable sshd, sendmail, make syslog
  29. listen only locally, enable clearing of `/tmp` and disable writing to
  30. `/var/spool/clientmqueue`:
  31. ```
  32. sysrc sshd_enable=NO
  33. sysrc sendmail_enable=NONE
  34. chown root:wheel /var/spool/clientmqueue
  35. chmod 000 /var/spool/clientmqueue
  36. sysrc syslogd_flags="-ss"
  37. sysrc clear_tmp_enable="YES"
  38. ```
  39. We can now move on and let you try create your first own customized `Fockerfile`.
  40. ## Trivial Example
  41. At the very basic level, Focker can be used simply as a jail building system.
  42. In order to get started you have to create a new directory:
  43. ```
  44. mkdir test-focker-build
  45. cd test-focker-build/
  46. ```
  47. with a file called `Fockerfile` inside:
  48. `touch Fockerfile`.
  49. Using your editor of choice (`ee` is a good one), you can now put a trivial
  50. directive in `Fockerfile`:
  51. ```
  52. base: freebsd-latest
  53. steps: []
  54. ```
  55. The `base` directive determines the starting point for your future image.
  56. A starting point is simply a pre-existing image. We will call this image
  57. the parent image. The chain always terminates with an image that doesn't have
  58. a parent. Such an image has to be created manually, by using `focker bootstrap`
  59. or perhaps transferred using `zfs send`/`zfs receive` combo.
  60. Now you are ready to build your first image. Run:
  61. `focker image build .`
  62. The `focker image build` command has the following syntax:
  63. ```
  64. usage: focker.py image build [-h] [--tags TAGS [TAGS ...]] [--squeeze]
  65. focker_dir
  66. positional arguments:
  67. focker_dir
  68. optional arguments:
  69. -h, --help show this help message and exit
  70. --tags TAGS [TAGS ...], -t TAGS [TAGS ...]
  71. --squeeze, -s
  72. ```
  73. As you can see, in our call `focker image build .` we have specified only the
  74. `focker_dir` parameter. It tells the Focker which directory contains the
  75. Fockerfile and potentially any additional files that you would like to include
  76. in your build (we will get to this later).
  77. You will see an output similar to the following:
  78. ```
  79. Waiting for /var/lock/focker.lock ...
  80. Lock acquired.
  81. poolname: zroot
  82. fname: ./Fockerfile
  83. spec: {'base': 'freebsd-latest', 'steps': []}
  84. base: zroot/focker/images/e4d5685@1 root: zroot/focker/images
  85. ```
  86. and if you run `focker image list` you will discover that you are still
  87. stuck only with your pre-existing base image. Why is that?
  88. Since we have specified no `steps` or more precisely we have specified
  89. an empty list of steps, the resulting image has the same checksum as the
  90. base image. This is the case since no modifications have been made and the
  91. image content is identical. To observe an effect, we could still run:
  92. `focker image build . -t test-build`
  93. This will instruct Focker to add a new tag to the resulting image. If you
  94. run `focker image list` now, you should see an output similar to:
  95. ```
  96. Tags Size SHA256 Base
  97. -------------------------------------- ------ -------- -------
  98. freebsd-latest freebsd-11.2 test-build 266M e4d5685 -
  99. ```
  100. Congratulations! Your first image has been tagged. We can now start
  101. filling the `steps` list to create something more useful.