diff --git a/_toc.yml b/_toc.yml index b15bb8d6..a325deb1 100644 --- a/_toc.yml +++ b/_toc.yml @@ -1,9 +1,19 @@ # Table of content # Learn more at https://jupyterbook.org/customize/toc.html # -# - file: intro -# - file: user_guide -# sections: +- file: index +- file: admin-guide/architecture + sections: + - file: admin-guide/architecture/overview + - file: admin-guide/architecture/accounts-and-groups + - file: admin-guide/architecture/authentication-authorization + - file: admin-guide/architecture/networking + - file: admin-guide/architecture/services-cron-etc + - file: admin-guide/architecture/version-control + - file: admin-guide/architecture/security + - file: admin-guide/architecture/active-directory + - file: admin-guide/architecture/certificates + # - file: user_standard_infrastructure # - file: user_standard_directory_structure # - file: user_ioc_configuration_modules_drivers @@ -15,5 +25,3 @@ # sections: # - file: admin_standard_infrastructure # - file: admin_standard_directory_structure - -- file: index \ No newline at end of file diff --git a/admin-guide/Makefile b/admin-guide/Makefile new file mode 100644 index 00000000..2afc6eb6 --- /dev/null +++ b/admin-guide/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LinuxInfrastructure.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LinuxInfrastructure.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/LinuxInfrastructure" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LinuxInfrastructure" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/admin-guide/_static/Shell Style Guide.html b/admin-guide/_static/Shell Style Guide.html new file mode 100644 index 00000000..2707ea85 --- /dev/null +++ b/admin-guide/_static/Shell Style Guide.html @@ -0,0 +1,1282 @@ +Shell Style Guide

Shell Style Guide

+ +

+ +Revision 1.26 +

+ + +
+ Paul Armstrong
+ Too many more to mention
+
+ +

+ Each style point has a summary for which additional information is available + by toggling the accompanying arrow button that looks this way: + ▶. + You may toggle all summaries with the big arrow button: +

▶ + Toggle all summaries +
Table of Contents
Shell Files and Interpreter Invocation
File Extensions SUID/SGID
Environment
STDOUT vs STDERR
Comments
File Header Function Comments Implementation Comments TODO Comments
Formatting
Indentation Line Length and Long Strings Pipelines Loops Case statement Variable expansion Quoting
Features and Bugs
Command Substitution Test, [ and [[ Testing Strings Wildcard Expansion of Filenames Eval Pipes to While
Naming Conventions
Function Names Variable Names Constants and Environment Variable Names Source Filenames Read-only Variables Use Local Variables Function Location main
Calling Commands
Checking Return Values Builtin Commands vs. External Commands
Conclusion
+ +

Background

+ + + +

Which Shell to Use

+ link + ▶ +
+ Bash is the only shell scripting language permitted for + executables. +
+
+
+ +

When to use Shell

+ link + ▶ +
+ Shell should only be used for small utilities or simple wrapper + scripts. +
+
+
+
+ + + +

Shell Files and Interpreter Invocation

+ +

File Extensions

▶ +
+ Executables should have no extension (strongly preferred) or a + .sh extension. + Libraries must have a .sh extension and should not be + executable. +
+
+
+ +

SUID/SGID

+ link + ▶ +
+ SUID and SGID are forbidden on shell scripts. +
+
+
+ +
+ +

Environment

+ +

STDOUT vs STDERR

+ link + ▶ +
+ All error messages should go to STDERR. +
+
+
+ +
+ +

Comments

+ +

File Header

+ link + ▶ +
+ Start each file with a description of its contents. +
+
+
+ +

Function Comments

+ link + ▶ +
+ Any function that is not both obvious and short must be commented. Any + function in a library must be commented regardless of length or + complexity. +
+
+
+ +

Implementation Comments

+ link + ▶ +
+ Comment tricky, non-obvious, interesting or important parts of your code. +
+
+
+ +

TODO Comments

+ link + ▶ +
+ Use TODO comments for code that is temporary, a short-term solution, or + good-enough but not perfect. +
+
+
+ +
+ +

Formatting

+

+ While you should follow the style that's already there for files that + you're modifying, the following are required for any new code. +

+ +

Indentation

+ link + ▶ +
+ Indent 2 spaces. No tabs. +
+
+
+ +

Line Length and Long Strings

▶ +
+ Maximum line length is 80 characters. +
+
+
+ +

Pipelines

▶ +
+ Pipelines should be split one per line if they don't all fit on one line. +
+
+
+ +

Loops

+ link + ▶ +
+ Put ; do and ; then on the same line as the + while, for or if. +
+
+
+ +

Case statement

+ link + ▶ +
+
    +
  • + Indent alternatives by 2 spaces. +
    • +
  • + A one-line alternative needs a space after the close parenthesis of + the pattern and before the ;;. +
    • +
  • + Long or multi-command alternatives should be split over multiple + lines with the pattern, actions, and ;; on separate + lines. +
    • +
+
+
+
+ +

Variable expansion

+ link + ▶ +
+ In order of precedence: Stay consistent with what you find; + quote your variables; + prefer "${var}" over "$var", but see details. +
+
+
+ +

Quoting

+ link + ▶ +
+
    +
  • + Always quote strings containing variables, command substitutions, + spaces or shell meta characters, unless careful unquoted expansion + is required. +
    • +
  • + Prefer quoting strings that are "words" + (as opposed to command options or path names). +
    • +
  • + Never quote literal integers. +
    • +
  • + Be aware of the quoting rules for + pattern matches in [[. +
    • +
  • + Use "$@" unless you have a specific reason to use $*. +
    • +
+
+
+
+ +
+ +

Features and Bugs

+ +

Command Substitution

+ link + ▶ +
+ Use $(command) instead of backticks. +
+
+
+ +

Test, [ and [[

+ link + ▶ +
+ [[ ... ]] is preferred over [, + test and /usr/bin/[. +
+
+
+ +

Testing Strings

+ link + ▶ +
+ Use quotes rather than filler characters where possible. +
+
+
+ +

Wildcard Expansion of Filenames

+ link + ▶ +
+ Use an explicit path when doing wildcard expansion of filenames. +
+
+
+ +

Eval

+ link + ▶ +
+ eval should be avoided. +
+
+
+ +

Pipes to While

+ link + ▽ +
+ Use process substitution or for loops in preference to piping to while. + Variables modified in a while loop do not propagate to the parent + because the loop's commands run in a subshell. +
+
+

+ The implicit subshell in a pipe to while can make it difficult to track + down bugs. + 

last_line='NULL'
+your_command | while read line; do
+  last_line="${line}"
+done
+
+# This will output 'NULL'
+echo "${last_line}"
+

+

+ Use a for loop if you are confident that the input will not contain + spaces or special characters (usually, this means not user input). + 

total=0
+# Only do this if there are no spaces in return values.
+for value in $(command); do
+  total+="${value}"
+done
+

+

+ Using process substitution allows redirecting output but puts the + commands in an explicit subshell rather than the implicit subshell that + bash creates for the while loop. + 

total=0
+last_file=
+while read count filename; do
+  total+="${count}"
+  last_file="${filename}"
+done < <(your_command | uniq -c)
+
+# This will output the second field of the last line of output from
+# the command.
+echo "Total = ${total}"
+echo "Last one = ${last_file}"
+

+

+ Use while loops where it is not necessary to pass complex results + to the parent shell - this is typically where some more complex + "parsing" is required. Beware that simple examples are probably + more easily done with a tool such as awk. This may also be useful + where you specifically don't want to change the parent scope variables. + 

# Trivial implementation of awk expression:
+#   awk '$3 == "nfs" { print $2 " maps to " $1 }' /proc/mounts
+cat /proc/mounts | while read src dest type opts rest; do
+  if [[ ${type} == "nfs" ]]; then
+    echo "NFS ${dest} maps to ${src}"
+  fi
+done
+

+
+
+ +
+ +

Naming Conventions

+ +

Function Names

+ link + ▶ +
+ Lower-case, with underscores to separate words. Separate libraries + with ::. Parentheses are required after the function name. + The keyword function is optional, but must be used + consistently throughout a project. +
+
+
+ +

Variable Names

+ link + ▶ +
+ As for function names. +
+
+
+ +

Constants and Environment Variable Names

+ link + ▶ +
+ All caps, separated with underscores, declared at the top of the file. +
+
+
+ +

Source Filenames

+ link + ▶ +
+ Lowercase, with underscores to separate words if desired. +
+
+
+ +

Read-only Variables

+ link + ▶ +
+ Use readonly or declare -r to ensure they're + read only. +
+
+
+ +

Use Local Variables

+ link + ▶ +
+ Declare function-specific variables with local. Declaration + and assignment should be on different lines. +
+
+
+ +

Function Location

+ link + ▶ +
+ Put all functions together in the file just below constants. Don't hide + executable code between functions. +
+
+
+ +

main

+ link + ▶ +
+ A function called main is required for scripts long enough + to contain at least one other function. +
+
+
+ +
+ +

Calling Commands

+ +

Checking Return Values

+ link + ▶ +
+ Always check return values and give informative return values. +
+
+
+ +

Builtin Commands vs. External Commands

+ link + ▶ +
+ Given the choice between invoking a shell builtin and invoking a separate + process, choose the builtin. +
+
+
+ +
+ +

Conclusion

+

+ Use common sense and BE CONSISTENT. +

+

+ Please take a few minutes to read the Parting Words section at the bottom + of the C++ Guide. +

+
+ +

+Revision 1.26 +

+ + \ No newline at end of file diff --git a/admin-guide/_static/selinux-coloring-book_A4-Stapled.pdf b/admin-guide/_static/selinux-coloring-book_A4-Stapled.pdf new file mode 100644 index 00000000..847143fe Binary files /dev/null and b/admin-guide/_static/selinux-coloring-book_A4-Stapled.pdf differ diff --git a/admin-guide/architecture.rst b/admin-guide/architecture.rst new file mode 100644 index 00000000..a48371f2 --- /dev/null +++ b/admin-guide/architecture.rst @@ -0,0 +1,19 @@ +============== + Architecture +============== + + +Contents: + +.. toctree:: + :maxdepth: 2 + + architecture/overview + architecture/accounts-and-groups + architecture/authentication-authorization + architecture/networking + architecture/services-cron-etc + architecture/version-control + architecture/security + architecture/active-directory + architecture/certificates diff --git a/admin-guide/architecture/accounts-and-groups.rst b/admin-guide/architecture/accounts-and-groups.rst new file mode 100644 index 00000000..a92c7d4c --- /dev/null +++ b/admin-guide/architecture/accounts-and-groups.rst @@ -0,0 +1,132 @@ +========== + Accounts +========== + +Linux accounts are generally stored and managed in Active Directory. + + +Account Types +------------- + +There are several types of accounts, which are usually indicated by a prefix or +suffix: + +- Normal accounts. No prefix or suffix. Older accounts are just last names, + newer accounts are LASTNAME_X, where X is the first letter of the given name. +- Global accounts. These have a ``gac-`` prefix. There are only a handful of + these on Linux so far, due to concerns about the lack of login restrictions. +- Administrator accounts. Marked with an ``-adm`` suffix. +- External users. These start with an ``ext-`` prefix and are provided to + external users, ie. those who are not PSI employees. +- Service accounts. These come with an ``svcusr-`` prefix and are used for + running services. + + +UID Allocation +-------------- + +============== =============== +Old accounts 1000-6000 +GFA accounts 10000-30000 +External users 30000-35000 +New accounts 35000+ +============== =============== + + +LDAP Attribute Mapping +---------------------- + +========= ======================== +Attribute LDAP Attribute +--------- ------------------------ +username ``msSFU30Name`` +UID ``msSFU30UidNumber`` +GID ``msSFU30GidNumber`` +home ``msSFU30HomeDirectory`` +shell ``msSFU30LoginShell`` +========= ======================== + + +Primary Groups +-------------- + +At PSI the user-private group scheme (UPG), the default on Red Hat +distributions, is **not** used. Instead, every user's primary group is usually +one specific to the group/department the user is working for, eg. ``unx-ait``. + +Users for whom there is no natural choice of primary group are assigned +``unx-nogroup``. + + +Low GIDs +-------- + +A number of groups have very low GIDs (<500), in particular:: + + unx-fkt:*:101: + unx-lke:*:110: + unx-abe:*:120:stingelin + unx-aea:*:130: + unx-lmu:*:140: + unx-lem:*:141: + unx-muesr:*:150: + unx-asm:*:210: + unx-lrp:*:220: + unx-zrp:*:221: + unx-ash:*:230: + unx-ppt:*:280: + unx-pmr:*:290: + unx-cmt:*:301: + unx-lfk:*:310: + unx-lch:*:320: + unx-lns:*:330: + unx-lap:*:340: + unx-lmn:*:350: + unx-asq:*:360: + unx-crpp:*:370: + unx-psq:*:380: + unx-psz:*:390: + unx-gabe:*:402: + unx-lrs:*:410: + unx-lth:*:420: + unx-lwv:*:430: + unx-les:*:440: + unx-dtp:*:451: + unx-lsu:*:490: + + +Shells +------ + +We support bash, and we also try to keep tcsh working. + +Currently bash, tcsh, and sh are used. The form for ordering accounts also +offers ``/bin/ksh`` and ``/bin/zsh``. The most popular by far is bash. + + +Special Accounts +---------------- + +``linux_ldap``: query LDAP +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `linux_ldap` account has read-only permissions on a limited subset of the +LDAP attributes. It is used by `nslcd`, for example, to query LDAP for users' +uid, gid, etc. + +The password should not be shared unnecessarily, but it does not need +to be specifically protected either. In fact, in earlier releases of +Scientific Linux it was necessary to have `/etc/nslcd.conf`, which +contains the password, world-readable. + +This account **must not** be given additional access or privileges. + +``linuxadjoin.psi.ch@D.PSI.CH`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This account is a pure AD account (ie it doesn't have Unix attributes like uid), +which is used to manage computer objects in AD automatically. In particular, it +is used to precreate computer objects to allow password-less AD joins. + +The account is only used on the Puppet server and has no (known) password. +Instead a keytab is used to get a valid Kerberos ticket. diff --git a/admin-guide/architecture/active-directory.rst b/admin-guide/architecture/active-directory.rst new file mode 100644 index 00000000..20a806f6 --- /dev/null +++ b/admin-guide/architecture/active-directory.rst @@ -0,0 +1,46 @@ +================== + Active Directory +================== + +Kerberos Realm and Settings +--------------------------- + +The AD domain (ie the Kerberos realm) is D.PSI.CH, **not** PSI.CH. The maximum +lifetime of a ticket is about a day, and a ticket can be renewed for about a +week. + + +Domain Controllers +------------------ + +In most networks ``d.psi.ch`` resolves to the correct names/IPs. One exception +is the DMZ. + +The domain controllers that are used internally are: + +- dc00 +- dc01 +- dc02 + +In the DMZ we need to use these instead: + +- rodc00 +- rodc01 + +It is important to note that the SSL certificates for the internal DCs are +**not** signed for ``dc0n.psi.ch``, but ``dc0n.d.psi.ch`` (note the extra `d`). +In certain contexts (eg in :manpage:`sssd.conf(5)`) specifying the DCs as +``dc0n.psi.ch`` fails because of this. + + +Linux Computer Objects +---------------------- + +Computer objects for Linux systems are created in +``OU=linux,OU=computers,OU=psi,DC=d,DC=psi,DC=ch``. We do not distinguish +between servers and workstations in AD (unlike the Windows team), as the +distinction isn't clear and it wouldn't help us anyway (as we don't use AD group +policies). + +We perform the join password-less, by pre-creating the computer object using a +script running on the Puppet master. diff --git a/admin-guide/architecture/authentication-authorization.rst b/admin-guide/architecture/authentication-authorization.rst new file mode 100644 index 00000000..a8ed7bcc --- /dev/null +++ b/admin-guide/architecture/authentication-authorization.rst @@ -0,0 +1,17 @@ +Authentication and authorization +================================ + +We use/support the following authentication mechanisms: + +- SSH keys/certificates +- Kerberos tickets (AD) +- Password (checked against AD), not for the ``root`` account + +Login is restricted to certain users and groups on each system. This is +implemented locally using :manpage:`pam_access(8)`. + +Shared Credentials +------------------ + +Shared credentials should be avoided, eg. by using ``.k5login`` or +``AuthorizedPrincipalsFile`` (see :manpage:`sshd_config(5)` for details). diff --git a/admin-guide/architecture/certificates.rst b/admin-guide/architecture/certificates.rst new file mode 100644 index 00000000..1e3633ec --- /dev/null +++ b/admin-guide/architecture/certificates.rst @@ -0,0 +1,5 @@ +Certificates +============ + +For services which are accessed by users, we use certificates provided by SWITCH +as described in Operations/Certificates. \ No newline at end of file diff --git a/admin-guide/architecture/networking.rst b/admin-guide/architecture/networking.rst new file mode 100644 index 00000000..6b05c0ae --- /dev/null +++ b/admin-guide/architecture/networking.rst @@ -0,0 +1,100 @@ +============ + Networking +============ + +The PSI network is quite fragmented and traffic is often restricted between +different subnets. As far as the Linux infrastructure is concerned we currently +distinguish two network zones: external (DMZ, Extranet, Tier3) and internal +(everything else). + +Each 'zone' is supposed to have one instance of the Linux infrastructure +systems, eg Yum repository. This is not entirely true at this point, but +progress has been made towards this goal. + +Within a zone all systems are allowed to connect to the respective +infrastructure systems. This page lists the exact connectivity requirements. + + +Requirements +============ + + +Configuration Management and Software Distribution +-------------------------------------------------- + +Eventually there should be a separate Puppet server in the DMZ, but for now we +use the internal one. + +======= ======================= ====================== ============= ==================== +Source Destination (internal) Destination (external) Ports Purpose +------- ----------------------- ---------------------- ------------- -------------------- +any puppet00 puppet00 8080, 8140 Puppet +any repo00 repo00 80, 443 Software Packages +======= ======================= ====================== ============= ==================== + + +Authentication +-------------- + +We use Active Directory for authentication, so Kerberos and encrypted LDAP +connections must be allowed to the domain controllers: + +======= ======================== ====================== ============= ======================== +Source Destination (internal) Destination (external) Ports Purpose +------- ------------------------ ---------------------- ------------- ------------------------ +any {dc00,dc01,dc02} rodc{00,01} 88, 464, 636 AD authentication/joins +======= ======================== ====================== ============= ======================== + + +Deployment +---------- + +For the successful deployment of Linux systems, the requirements below must be +met. Systems are currently not deployed in external networks (DMZ, Extranet, +Tier3), so this only applies internally. + +- `Configuration Management and Software Distribution`_ +- `Authentication`_ + +In addition, the following: + + +======= ============ ================ =================== +Source Destination Ports Purpose +------- ------------ ---------------- ------------------- +any boot00 UDP/69, 80, 443 PXE/Kickstart +======= ============ ================ =================== + +Finally, having DHCP is helpful, but not necessary. + + +Monitoring/Reporting +-------------------- + +======= ====================== ====================== ============= ====================== +Source Destination (internal) Destination (external) Ports Purpose +------- ---------------------- ---------------------- ------------- ---------------------- +any influx00 influxdmz00 8086 Performance metrics +any rep N/A 443 Reporting (turned off) +======= ====================== ====================== ============= ====================== + + +Configuration +============= + +IPv6 +---- + +Starting with RHEL 7 we do *not* disable IPv6 completely. We leave it on, but do +not configure any addresses. The routers at PSI also don't send router +advertisements, the DHCP server doesn't provide IPv6 addresses. + +As a consequence, the network interfaces on these systems only have a link-local +address and IPv6 isn't actually used in practice. The reason for leaving IPv6 +enabled is to slowly gain experience with the protocol. So far we have run into +two issues: + +- In one network the router *did* send router advertisements, but the route + didn't actually work. +- Some DNS names resolve to IPv6 addresses as well as IPv4 ones. Combined with + the first issue, this caused deployment to fail on a console. diff --git a/admin-guide/architecture/overview.rst b/admin-guide/architecture/overview.rst new file mode 100644 index 00000000..318e5cd7 --- /dev/null +++ b/admin-guide/architecture/overview.rst @@ -0,0 +1,60 @@ +Overview +======== + +Documentation +------------- + +This admin guide as well as the user guide are written using Sphinx with +ReStructured Text. In addition, Git repositories usually contain a README.md +file. + +This `admin guide `_ is +automatically rebuilt when changes are pushed. + + +Deployment +---------- + +We generally deploy systems using PXE/Kickstart, even VMs. There is a VM +template, but it only defines the standard hardware/VM settings. No software is +pre-installed. + +We use an iPXE image, which retrieves its client-specific configuration from a +web service, which also generates the client-specific Kickstart file. + +For systems where network booting isn't possible, eg. because DHCP isn't +available, we can boot from USB as well. + +The installation process is very roughly: + +1. Install a minimal system plus the Puppet agent using Kickstart +2. Reboot +3. On first boot, run Puppet, which installs/configures the rest + + +OS, Software, and Licenses +-------------------------- + +We use Red Hat Enterprise Linux 7 (aka RHEL 7). The licenses are provided by +ETHZ, and we mirror the software from their Satellite server locally. We do not +have direct access to Red Hat support, but we can access the Red Hat customer +portal. + +In addition to RHEL, we use/make available the following: + +- EPEL (all of it) +- ELREPO (mostly for the Nvidia drivers) +- Puppet +- NoMachine + +In addition there are several internal repositories. + + +Configuration Management and Automation +--------------------------------------- + +We use `Puppet `_ for configuration management on Linux +systems. Configuration data is managed using `Hiera +`_. + +Scripts are generally written in bash or Python. diff --git a/admin-guide/architecture/security.rst b/admin-guide/architecture/security.rst new file mode 100644 index 00000000..b99b3324 --- /dev/null +++ b/admin-guide/architecture/security.rst @@ -0,0 +1,35 @@ +========== + Security +========== + +Access Control +-------------- + +Access control on systems is done using ``pam_access``, ``pam_listfile``, etc. +By default, remote access is only granted to certain users/groups configured in +Hiera (see ``profile::aaa`` for details). Local access is currently +unrestricted, ie. every valid PSI Linux account can log in locally. + + +``root`` login +-------------- + +- only with keys/Kerberos tickets +- only through bastion hosts (wmgt*, two-factor auth) by default + + + + + +SELinux +------- + +- depends on the role, enforcing by default, enforcing on all infrastructure + systems + + +Firewall/tcpwrappers +-------------------- + +- tcpwrappers yes +- firewall no diff --git a/admin-guide/architecture/services-cron-etc.rst b/admin-guide/architecture/services-cron-etc.rst new file mode 100644 index 00000000..62db8eec --- /dev/null +++ b/admin-guide/architecture/services-cron-etc.rst @@ -0,0 +1,35 @@ +========= + systemd +========= + + +SysV init scripts +----------------- + +We only use SysV init scripts if systemd unit files are not provided by the +software in question. Our own services are all configured through systemd unit +files. + + +``cron`` vs. systemd timers +--------------------------- + +While we start/enable cron by default, we use systemd timers for everything. The +advantages are: + +- unified view with other system entities, eg. services, mounts, devices +- easy log filtering with ``journalctl -u TIMER`` +- easy introspection via ``systemctl list-timers``, ``systemctl cat TIMER``, + etc. + + +Mounts +------ + +Mounts, including automounts, are configured in /etc/fstab. Generating the mount +units directly leads to certain difficulties (SELinux problems which we never +quite figured out, stale mount unit files when the mountpoint changes, etc). +Automounts can be configured by adding ``x-systemd.automount`` to the mount +options. + +We do start the ``autofs`` service on some systems, to provide the ``-net`` map. diff --git a/admin-guide/architecture/version-control.rst b/admin-guide/architecture/version-control.rst new file mode 100644 index 00000000..f7d68b5e --- /dev/null +++ b/admin-guide/architecture/version-control.rst @@ -0,0 +1,66 @@ +Version control +--------------- + +We use the internal `PSI Gitlab server `_ for version +control. On this server we use a single repository group (``linux-infra``) for +all infrastructure-related repositories, because this way a number of things +have to be configured only once, e.g. members. In addition milestones and labels +are group-wide concepts in Gitlab, and it is very useful to have those apply to +all repositories. Finally it is easy to see all issues and merge requests for a +repository group. + + +Repositories +~~~~~~~~~~~~ + +Our repositories are configured in the following way: + +The ``puppet`` repository +......................... + +- Fast-forward merges only + + This keeps the history linear without merge commits, which makes it easier to + read. + +- Merges to ``prod`` or ``preprod`` require one approval + +- Approval is revoked when further changes are pushed to an already approved + merge request. + +- The default branch is called ``prod``. There is no ``master`` branch. +- The ``prod`` branch is protected. +- The ``preprod`` branch is protected. + + +Hiera repositories +.................. + +These repositories contain Hiera data. There is exactly one repository per sysdb +environment. The repository for environment ``foo`` is called ``data-foo``. + +Access is granted to the owner and admins of the corresponding sysdb environment. + + +Development workflow +~~~~~~~~~~~~~~~~~~~~ + +We steer development through Gitlab issues. + +For every change, be it a new feature, bug fix, or improvement, we create an +issue on the relevant repository. Issues that have broader implications and do +not naturally belong to a code repository, go into the ``org`` repository. An +example would be a change of the development workflow or repository +authorization. + +When starting work on a change, the developer first assigns the issue to +themselves. + +Once the developer has finished development and tested the change, they rebase +their changes to the ``prod`` branch, push the changes to a new branch, and +opens a merge request to the ``preprod`` branch. Each issue ``#N`` being fixed +must be mentioned at the start of the commit message in the form ``Fix #N``. + +Other developers will review the merge request. If they approve it, either the +approving or the original developer may accept it, which will trigger the actual +merge. diff --git a/admin-guide/conf.py b/admin-guide/conf.py new file mode 100644 index 00000000..a5f8e532 --- /dev/null +++ b/admin-guide/conf.py @@ -0,0 +1,242 @@ +# -*- coding: utf-8 -*- +# +# Linux Infrastructure documentation build configuration file, created by +# sphinx-quickstart on Mon Apr 11 13:24:16 2016. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'Linux Infrastructure' +copyright = u'2016, PSI Linux Administrators' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'LinuxInfrastructuredoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'LinuxInfrastructure.tex', u'Linux Infrastructure Documentation', + u'PSI Linux Administrators', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'linuxinfrastructure', u'Linux Infrastructure Documentation', + [u'PSI Linux Administrators'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'LinuxInfrastructure', u'Linux Infrastructure Documentation', + u'PSI Linux Administrators', 'LinuxInfrastructure', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/admin-guide/deployment.rst b/admin-guide/deployment.rst new file mode 100644 index 00000000..56b9c5ca --- /dev/null +++ b/admin-guide/deployment.rst @@ -0,0 +1,25 @@ +Deployment +========== + +Linux systems are generally deployed using PXE and Kickstart. We use iPXE, which +can retrieve its configuration via HTTP(S) and therefore gives us a lot of +flexibility, because the iPXE configuration can be generated on the fly with the +specific settings needed by the booting client. In the same way the Kickstart +configuration for the RHEL installer is auto-generated. + +The information used for generating the iPXE and Kickstart configurations is +stored in the sysdb (see below). The sysdb is accessible through a web api, and +a command line client is available. + +When PXE boot is not an option, e.g. in restricted networks, it is possible to +start iPXE from a USB stick or other media. + +.. toctree:: + :maxdepth: 2 + + deployment/ipxe + deployment/kickstart + deployment/partitioning + deployment/sample + deployment/infrastructure + deployment/workflow diff --git a/admin-guide/deployment/infrastructure.rst b/admin-guide/deployment/infrastructure.rst new file mode 100644 index 00000000..9de7af60 --- /dev/null +++ b/admin-guide/deployment/infrastructure.rst @@ -0,0 +1,94 @@ +============================ +Deploying the infrastructure +============================ + +Introduction +============ + +The deployment infrastructure is composed of: + + - one sysdb server; + - one puppet server; + - one repository server. + +We currently have two infrastructures in place, one for testing and the +other for production, with the following hostnames: + ++--------------------+----------------+-----------------+ +| Role | testing host | production host | ++====================+================+=================+ +| sysdb server | boot00-test | boot00 | ++--------------------+----------------+-----------------+ +| puppet server | puppet00-test | puppet00 | ++--------------------+----------------+-----------------+ +| repository server | repo00-test | repo00 | ++--------------------+----------------+-----------------+ + +The Sysdb Server +---------------- + +The sysdb server is a server running HTTP(S) services needed by +other components of the deployment infrastructure, specifically to: + + - setup (add/remove/modify) the hosts managed by the system; + - get the iPXE file for the managed hosts; + - get the Kickstart file for the managed hosts. + +The code for these services is avaiable at ``_. + +the Puppet Server +----------------- + +The puppet server is a rather standard puppet master, configured to +use ``sysdb`` informations as ENC. + +The Repo Server +--------------- + +The service that provides clones of different repositories (RHEL, +Puppetlabs, Google Chrome) plus some internally developed ones for +specific products (eg. GPFS). + +You can reach the production one at: ``_. + +Deployment of an infrastructure server +====================================== + +The procedure is not fully automated and completely documented. + +The reference repo server is ``_. + +The installation of an infrastructure server uses: + - ETH repositories (since the repo server is not assumed to be available) + - PXE only and static kickstart file (since the boot server is not supposed to be available) + +After the installation, inside ``/root/bootstrap/instcode`` there is a script for each +server, called ``{puppet,boot,repo}-server``. +The script should be run manually and some user interaction is needed. + +Before to install you need to have: +- a copy of the ssh root user keys and ssh server keys +- a Red Hat Satellite Key. You can get it via the RHN Satellite Account at ETH + +So to install eg. ``puppet00-test`` the procedure would be: + + - ensure on the Satellite web site that the system is not present (Systems-> Overview page) + - copy the kickstart on ``/afs/psi.ch/project/linux/www/kickstart/configs/linux-infra/`` + - copy the pxe in ``/afs/psi.ch/service/linux/tftpboot/pxelinux.cfg/`` + - install the server booting from network + - after the installation the server will stop + - reboot it + - login on the server + - copy the ssh key + - enter the ``/root/bootstrap/instcode`` directory + - optionally change the branch + - run ``./puppet-server`` + + +Please note that in some cases the ETH repo used during the +installation is not properly working. + +In the case you are not redeploying the repo server, then it can be +used instead of the ETH one, changing properly the PXE and the +kickstart file. + diff --git a/admin-guide/deployment/ipxe.rst b/admin-guide/deployment/ipxe.rst new file mode 100644 index 00000000..d11805b6 --- /dev/null +++ b/admin-guide/deployment/ipxe.rst @@ -0,0 +1,61 @@ +PXE-booting with iPXE +===================== + +UEFI +---- + +iPXE supports UEFI and so do we. This requires the ``ipxe.efi`` boot image. + + +Process +------- + +When a system PXE boots, the DHCP server will boot either pxelinux in legacy +mode or grub on UEFI. It is still possible to load ipxe from either of these. +With the right option, the boot process is pointed to ``boot00.psi.ch`` and one +of the following boot images: + +- ``ipxe.efi`` for systems using UEFI +- ``ipxe.lkrn`` for all other systems + +The system downloads the image and executes it. + +The image contains a small iPXE script, which makes iPXE retrieve its actual +configuration from a web service running (usually) on ``boot00.psi.ch``. +Specifically, it queries the URL +``https://boot00.psi.ch/ipxe/v1/config?mac=``, where ```` is the MAC +address of the interface used by iPXE. + +The web service on ``boot00.psi.ch`` will generate the iPXE configuration on the +fly, depending on whether the system is supposed to be reinstalled and if so, +which distribution it is supposed to use. The menu offers other options as well, +e.g. an interactive iPXE shell and a memory test. + + +Building the iPXE boot image +---------------------------- + +The steps for building an iPXE image are + +1. Clone ``git@git.psi.ch:linux-infra/ipxe-build.git`` +2. Change into the new directory +3. Run the ``refresh-ipxe.sh`` script. This will check out the iPXE source code + mirror from ``git.psi.ch``. +4. Run the ``build.sh`` script. This will use the named configurations in the + ``ipxe-build`` repository to compile two iPXE images: ``src/bin/ipxe.lkrn`` + (legacy boot) and ``src/bin-x86_64-efi/ipxe.efi`` (UEFI). + + +As described above, we use an iPXE boot image with an embedded script looking +roughly like the following:: + + #!ipxe + + dhcp && goto dhcp_succeeded + + shell + #prompt for network info + + :dhcp_succeeded + + chain http://boot00.psi.ch/ipxe/v1/config?mac=${netX/mac} diff --git a/admin-guide/deployment/kickstart.rst b/admin-guide/deployment/kickstart.rst new file mode 100644 index 00000000..a4673469 --- /dev/null +++ b/admin-guide/deployment/kickstart.rst @@ -0,0 +1,11 @@ +Kickstart +========= + +The auto-generated Grub or iPXE configuration will, when installing RHEL, instruct +the RHEL installer to download the Kickstart configuration from +``https://boot00.psi.ch/kickstart/v1/config?fqdn=&instrepo=``, +where ```` is the FQDN of the host to be installed, and ```` is +the installation repository to be used. + +The web service will auto-generate the Kickstart configuration for the client +based on information in sysdb, e.g. the release to be installed. diff --git a/admin-guide/deployment/partitioning.rst b/admin-guide/deployment/partitioning.rst new file mode 100644 index 00000000..39625992 --- /dev/null +++ b/admin-guide/deployment/partitioning.rst @@ -0,0 +1,30 @@ +Partitioning +============ + +Partitions system are configured with a standard schema using LVM, so +that they can be possibly changed afterwards. + +By default the whole space available on the first block device is used +and any existing partition is removed. +The default partition schema is: + + - create one primary ``/boot`` partition of 1Gb; + - create the ``vg_root`` Volume Group that uses the rest of the disk; + - on ``vg_root`` create the following logical volumes: + - ``lv_root`` of 12 Gb size for ``/root``; + - ``lv_var`` of 8 Gb size for ``/var``; + - ``lv_var_log`` of 2 Gb size for ``/var/log``; + - ``lv_tmp`` of 2 Gb size for ``/tmp``. + + +Custom Partitioning +------------------- +It is possible to customize the partitioning by using the ``partitions`` attribute on sysdb. + +The ``partitions`` attribute can take two values: + + - ``manual``: this will not partition the disks and the installation process will wait for manual partitioning; + - ````: it is assumed to be a file containing the partitioning commands as used in kickstart. + +If it is not possible to download the given URL the system fails-back to manual at installation time. +Please also note that no check is done on the URL content. diff --git a/admin-guide/deployment/sample.rst b/admin-guide/deployment/sample.rst new file mode 100644 index 00000000..87117b75 --- /dev/null +++ b/admin-guide/deployment/sample.rst @@ -0,0 +1,60 @@ +Sample deployment of a new server +================================= + +In this section we describe the deployment of a new server from +scratch. +All the operations will be performed using `bob`, the command-line +client for interacting with `sysdb`. + +The informations we need are: + + - the server name: ``logging-ra.psi.ch`` + - the server MAC address: ``23:3d:ef:33:11:22`` + - the server role: ``role::logging_server`` + - the server environment in puppet: ``production`` + - the sysdb environment: ``daas`` + +On our laptop, where we have a local copy of `bob`, we first setup +some environment variables to have shorter commands: :: + + export PSI_BOB_URL=https://boot00-test.psi.ch/sysdb + export PSI_BOB_USER=talamo_i + +The $PSI_BOB_USER is needed because our local user is different from +the one on sysdb. It could also be specified on the command line or +let `bob` take the local username. + +We then create a deployment environment:: + + bob env add daas talamo_i daas-admins 'DaaS Cluster' + +We add the node to the environment, specifing ``netboot`` as +the boot action :: + + bob node add logging-ra.psi.ch daas netboot + +We setup its MAC address: :: + + bob node add-mac logging-ra.psi.ch 23:3d:ef:33:11:22 + +And we finally setup the puppet role and puppet environment: :: + + bob node set-attr syslog-ra.psi.ch puppet_role=role::log_server + bob node set-attr syslog-ra.psi.ch puppet_env=production + + +PXE server-side configuration +----------------------------- + +In case the node is configured to use legacy BIOS mode (and +not UEFI mode) the following has to be run on the PXE server to make +the node boot the ipxe image: :: + + cd /afs/psi.ch/service/linux/tftpboot/pxelinux.cfg/ + ln -sf lxprod logging-ra + MAC='the::node::mac::address' + MACFILENAME="01-`echo $MAC|tr 'A-Z' 'a-z'| sed 's/:/-/g'`" + ln -sf logging-ra $MACFILENAME + +Otherwise the node will boot with the old pxe configuration. In such +case is possible to boot ipxe typing `lxprod` on the PXE command line. diff --git a/admin-guide/deployment/workflow.rst b/admin-guide/deployment/workflow.rst new file mode 100644 index 00000000..1c4167eb --- /dev/null +++ b/admin-guide/deployment/workflow.rst @@ -0,0 +1,165 @@ +=================================== +Deploying New Environment: Workflow +=================================== + +Introduction +============ + +Deploying a new environment requires the following: + 1. Configuring the environment in **bob** + 2. Configuring the environment in GIT (``git.psi.ch``) + + - Environment format: ``data-`` + - And change permissions accordingly + + 3. Configuring the environment in Puppet (``puppet00.psi.ch``) + +Configuring the environment in sysdb +------------------------------------ + +Bob allows to create a new environment in ``sysdb`` by using the ``bob +env`` option. You must have permissions to do that. + + +You must belong to the ``sysdb-admins`` group that is actually +configured on the local ``/etc/group`` file. A migration to Active +Directory should be done for that group. + +To list current defined environments run:: + + bob env list + +To add a new environment, run:: + + bob env add "" + +In example, for the MeG cluster:: + + bob env add meg caubet_m unx-hpc_adm "MeG Cluster" + +Test new environment in BOB +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to test that environment was successfully created:: + + bob env list | grep + +In example:: + + caubet_m@caubet-laptop:~/GIT/admin-guide/deployment$ bob env list | grep meg + meg caubet_m unx-hpc_adm MeG Cluster + +Configuring the environment in GIT +---------------------------------- + +Current **GIT** server at **PSI** is ``git.psi.ch``. Every new environment should in principle belong to the **linux-infra** project. + +You must belong to the ``puppet_env`` Active Directory group in order to be able to create new projects. + +In order to create a new environment in **GIT**, you should access and login in the following link: https://git.psi.ch/linux-infra/. Here you can see +the different environments and **GIT** projects belonging to the **linux-infra** group. + +The steps to create and configure a new **GIT** project are: + +1. Create a new project (environment). It can be done here: https://git.psi.ch/projects/new + + - Go to ``[Blank project] Tab`` (which is the *default* tab) + - Change ``[Project Path]`` as follows: + - https://git.psi.ch/ + ``linux-infra`` + - Define ``[Project Name]``, which *must* have the following format: + - ``data-`` where ```` is the one defined in **Bob** + - *[Optional]* Specify ``[Project description]`` + - Specify ``[Visibility Level]``: + - Should be ``Internal`` + +2. Configure *project* permissions as follows: + + - ``[data-[Settings]->[Repository]``, or directly: https://git.psi.ch/linux-infra/data-(environment_name)/settings/repository + - ``[Deploy Keys]`` -> select ``root@puppet00.psi.ch'`` -> click on ``'Enable'`` + - ``[data-[Settings]->[Members]``, or directly: https://git.psi.ch/linux-infra/data-(environment_name)/project_members + - Setup specific permissions for specific users or groups. In example: + - Set project ``Master``: + - ``[Select members to invite]`` (``caubet_m``) + ``[Choose a role permission]`` (``Master``) + ``[Add to project]`` + - Set other roles: + - ``[Select members to invite]`` (``ozerov_d``) + ``[Choose a role permission]`` (``Developer``) + ``[Add to project]`` + - ``[data-[Settings]->[Integrations]``, or directly: https://git.psi.ch/linux-infra/data-(environment_name)/settings/integrations + - Add WebHook as follows: + - ``[URL]``: http://puppet00.psi.ch/events/dataupdate + - (Checked) ``[Push events]``. Uncheck the rest. + - ``[SSL verification]`` -> (uncheck) ``[Enable SSL verification]`` + - Confirm information from above, and click on ``[Add webhook]`` to add the new WebHook. + +Test new environment in GIT +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to test that environment was successfully created:: + + git clone git@git.psi.ch:linux-infra/data-.git + +In example:: + + caubet_m@caubet-laptop:~/GIT$ git clone git@git.psi.ch:linux-infra/data-meg.git + Cloning into 'data-meg'... + X11 forwarding request failed + warning: You appear to have cloned an empty repository. + +Configuring the environment in Puppet +------------------------------------- + +Current *test* **Puppet** server is ``puppet00-test.psi.ch``. Current *production* **Puppet** server is ``puppet00.psi.ch``. This documentation will take as an example an environment +deployed in the *production* server ``puppet00.psi.ch``. + +You must have ``root`` access to the Puppet server in order to be able to configure it. + +Steps are: + +1. Login in to the Puppet server:: + + ssh root@puppet00.psi.ch + +2. Clone the already created **GIT** project to the ``/srv/puppet/data`` path, which contains all the different projects (Bob environments):: + + git clone git@git.psi.ch:linux-infra/data-.git /srv/puppet/data/ + + # In example: + git clone git@git.psi.ch:linux-infra/data-meg.git /srv/puppet/data/meg + +3. Change permissions to ``plidata.puppet`` for the new directory ``/srv/puppet/data/``:: + + chown -R plidata.puppet /srv/puppet/data/ + + # In example: + chown -R plidata.puppet /srv/puppet/data/meg + +At this point, everything should be configured and we can proceed to test that it works. + +Test new environment in Puppet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In order to test that environment was successfully created:: + + git clone git@git.psi.ch:linux-infra/data-.git + +Add a new file .yaml in to the project:: + + cd data- + touch .yaml + git add .yaml + git commit -a -m "Added first empty file" + git push + +After a few seconds (needs time to trigger the change), check in ``puppet00.psi.ch:/srv/puppet/data/`` that file was successfully triggered (copied) to the puppet server from **GIT**:: + + ssh root@puppet00.psi.ch ls /srv/puppet/data//.yaml + +Full real example:: + + git clone git@git.psi.ch:linux-infra/data-meg.git + cd data-meg + touch meg.yaml + git add meg.yaml + git commit -a -m "Added first empty file" + git push + sleep 5 + ssh root@puppet00.psi.ch ls /srv/puppet/data/meg/meg.yaml + diff --git a/admin-guide/guidelines.rst b/admin-guide/guidelines.rst new file mode 100644 index 00000000..9bc51418 --- /dev/null +++ b/admin-guide/guidelines.rst @@ -0,0 +1,70 @@ +Guidelines +========== + +.. toctree:: + :maxdepth: 1 + + guidelines/conventions + + +Version Control +--------------- + +Everything must be in version control before being used on production systems. +In particular, scripts and other software, SPEC files for packages, relevant +documentation, Puppet code, etc. + +Git Hooks +--------- + +`This repository `_ provides a pre-commit git hook that checks code compliance to different standards. + +Hiera Code +---------- + +The naming of the variables inside Hiera depends on the scope usage of the variables. + +The variables beeing used only inside one specific class +will be named ``base_class_name::variable`` where ``base_class_name`` is the last part of class name, without the part before the last ``::`` separator. +Eg. the ``permit_root_login`` variable for the ``profile::ssh_server`` class will be named ``ssh_server::permit_root_login``. + +When a variable is shared between a client and a server, we will prepend the variable name with the service name. +Eg. the ``grid_name`` parameter for ganglia service, used inside both client and server configuration, will be named ``ganglia::grid_name``. + +*Note:* this could potentially bring to conflicts, if we want to specify hiera values to be used both inside roles and profiles with the same name. +Do we want that? + + +Code Reviews +------------ + +All code must be reviewed by at least one other team member with write access to +the repository before pushing it. This will help keep the style consistent and +increase familiarity with the code base. + + +External Code +------------- + +Although the installation infrastructure makes large usage of external code the system +has to avoid as much as possible dependency from external services availability. +A WAN outage or a remote http server failure should not influence the installation system. +For this reason, all the external code is mirrored internally in specific git repositories. + +Servers and services +-------------------- + +Every server should support exactly one service, e.g. Puppet, or FTP. This makes +the services more independent (e.g. for downtimes), simplifies the structure of +the corresponding Puppet code, makes it easier to reason about the environment, +and prevents conflicts regarding certain configuration settings. + + +Development Workflow +-------------------- + +The general inspiration comes from `this post +`_. + +Regarding the puppet code this is more detailed description of our current +workflow: diff --git a/admin-guide/guidelines/conventions.rst b/admin-guide/guidelines/conventions.rst new file mode 100644 index 00000000..009ce1f4 --- /dev/null +++ b/admin-guide/guidelines/conventions.rst @@ -0,0 +1,52 @@ +Conventions +=========== + +Naming convention for servers +----------------------------- + +Server names have the form ``purpose[0-9][0-9]{,-test}.psi.ch``, where +``purpose`` is the purpose of the server or the service provided by it. Examples are: + +- ``puppet00.psi.ch`` is the **productive** puppetmaster +- ``repo00-test.psi.ch`` is the **test** Yum repository server + +When putting system names into configuration files, we always use lower case and +the fully qualified domain name. Good: ``puppet00.psi.ch``. Bad: ``puppet00`` or +``PUPPET00.PSI.CH``. + + +Names for programs +------------------ + +The general conventions regarding filenames apply (see `File system hierarchy +and filenames`_). In addition, scripts should not include a suffix indicating +the language they are written in. The latter is an implementation detail and +does not matter to the caller of the script/program. A good name could be +``pli-system-info``, a bad one would be ``pli-system-info.sh``. + + +File system hierarchy and filenames +----------------------------------- + +Files should generally be placed where the distribution and/or the `FHS +`_ expect them. Deviations and clarifications are +documented in this section. + +The base directory for files is ``/usr`` if the files are relevant to end-users, +``/opt/pli`` if the files are relevant only to Linux administrators. This avoids +polluting the PATH for end-users as well as naming conflicts. + +Executables (scripts or otherwise) that are meant for interactive use should go +into ``BASE/bin`` or ``BASE/sbin`` as appropriate. + +Executables which are primarily called by other executables to implement part of +their functionality should be place in ``BASE/libexec``. This avoids polluting +``$PATH``. + +Files and directories should have names starting with ``pli-`` or be placed in a +directory with such a name. This makes it obvious whether a file belongs to an +internal package and avoids collisions. + +Note: this section used to recommend ``psi-`` as the prefix. It turns out that +this prefix is being used in various other places already, hence we use +``pli-``, where PLI stands for PSI Linux Infrastructure. diff --git a/admin-guide/index.rst b/admin-guide/index.rst new file mode 100644 index 00000000..1b0eab61 --- /dev/null +++ b/admin-guide/index.rst @@ -0,0 +1,34 @@ +.. Linux Infrastructure documentation master file, created by + sphinx-quickstart on Mon Apr 11 13:24:16 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Linux Infrastructure's documentation! +================================================ + +Contents: + +.. toctree:: + :maxdepth: 2 + + architecture + guidelines + deployment + puppet + selinux + software + mgmt-tools + operations + third-party + troubleshooting + more + legacy + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/admin-guide/legacy.rst b/admin-guide/legacy.rst new file mode 100644 index 00000000..8f5a7c9c --- /dev/null +++ b/admin-guide/legacy.rst @@ -0,0 +1,20 @@ +================ + Legacy Systems +================ + +This section describes the PSI legacy Linux environment, ie. those systems +running Scientific Linux 6 and earlier. Unlike the rest of the admin guide, this +section is mostly a plain import of existing snippets of documentation, which +were created in a variety of formats. + +.. toctree:: + :maxdepth: 2 + + legacy/communication + legacy/installation + legacy/misc + legacy/monitoring + legacy/puppet + legacy/services + legacy/software + legacy/storage diff --git a/admin-guide/legacy/communication.rst b/admin-guide/legacy/communication.rst new file mode 100644 index 00000000..45d3218b --- /dev/null +++ b/admin-guide/legacy/communication.rst @@ -0,0 +1,48 @@ +Communication +============= + +There are several communication channels: + +1. Mailing lists: linux-announce and linux-discuss +2. Trouble tickets (via the helpdesk). +3. IT supporter meetings + + +Mailing lists +------------- + +There are three mailing lists: + +1. ``puppet-devel@lists.psi.ch`` + + This list is for technical discussions concerning Linux at PSI, in particular + the infrastructure, ie Puppet, iPXE, etc. + +2. ``linux-announce@lists.psi.ch`` + + This list is used for announcements of new updates, changes, events, etc. + Only admins can post (as configured on the mailing list server). + +3. ``linux-discuss@lists.psi.ch`` + + This list is meant for discussions related to the PSI Linux environment. Any + subscriber can post. + +Mails to ``linux-announce`` should follow a standard format. In particular, the +subject line should start with a tag describing the kind of announcement. +Already established tags are: + +- ``[Change]`` +- ``[Updates]`` + + +Trouble tickets +--------------- + +These are for incidents and requests. + + +Linux Support Meetings +---------------------- + +These happen roughly every two weeks. diff --git a/admin-guide/legacy/installation.rst b/admin-guide/legacy/installation.rst new file mode 100644 index 00000000..d097d67b --- /dev/null +++ b/admin-guide/legacy/installation.rst @@ -0,0 +1,65 @@ +Installation +============ + +This section describes the various installation methods, e.g. PXE. + +PXE Server +---------- + +The PXE server is ``pxeserv01.psi.ch``, running SL 5.1. + +Directory structure +~~~~~~~~~~~~~~~~~~~ + +The usual ``/tftpboot/pxelinux.cfg`` setup. The ``pxelinux.cfg`` +directory contains the following subdirectories: + +- ``Boot``: could be Windows-related +- ``centos``: CentOS 7.0, 7.1, and 7.2 +- ``dl``: diskless systems +- ``pxelinux.cfg``: PXELINUX configuration +- ``scientific``: Scientific Linux, 3.01 -> 7.0, partly obsolete +- ``tools``: + + +PXELINUX +-------- + +The PXELINUX configuration files are in ``pxeserv01:/tftpboot``. + +The ``default`` file currently contains 127 labels. + + +Scientific Linux 6, 64bit +~~~~~~~~~~~~~~~~~~~~~~~~~ + +One thing to note is that the +[Kickstart file](http://linux.web.psi.ch/kickstart/configs/sl64-64-desk-stable-ks.cfg) +is modified during installation by the +[``ks_pre.sh``](http://linux.web.psi.ch/dist/scientific/64/kickstart/bin/ks_pre.sh) +script. + + +Kickstart +--------- + +The documentation on Kickstart files is currently based on +``sl64-64-desk-stable-ks.cfg``, the default Kickstart file for SL6. + +In the ``%pre`` section a distribution-specific script ``ks_pre.sh`` +is downloaded and executed. Errors are not handled. The script +*modifies* the Kickstart file. The latter contains markers +``#BEGIN_MAIN`` and ``#END_MAIN`` to mark the region to be modified. + + +Custom keys +~~~~~~~~~~~ + +The Kickstart files defines variables ``INIT_KEYS`` and +``APPEND_KEYS`` and exports them for use by ``ks_pre.sh``. The latter +attempts to download an environment file and a script +``custom_pre.sh`` for each key and sources them. + +The custom key related files are stored below +``/afs/psi.ch/software/linux/dist/scientific/$OSVERSION/custom/``. +Examples for custom keys are ``DesktopTesting`` and ``DesktopStable``. diff --git a/admin-guide/legacy/misc.rst b/admin-guide/legacy/misc.rst new file mode 100644 index 00000000..9980ee83 --- /dev/null +++ b/admin-guide/legacy/misc.rst @@ -0,0 +1,37 @@ +Miscellaneous +============= + +This section contains (potentially out-of-date or obsolete) documents +from the wiki, various places on AFS, etc. Most of them should be +integrated in the other sections properly, the rest removed. + +.. toctree:: + :maxdepth: 1 + + misc/afstowindowsloginchangeinsl4andsl5 + misc/configureldaponpsipuppet3 + misc/createanewkickstartinstallationforfedora10 + misc/disklessclientsl60 + misc/dkmsbasics + misc/firefoxpreferenceshowto + misc/howtoeditinstallimg + misc/howto-start-vncserver + misc/kernelmodulee1000eupdateforsl5.1 + misc/linuxhowtolookupforpcidevicesandcorrespondingmodulesinsl5 + misc/linuxhowto-rpm-updatepsi-desktoppackageonsl5 + misc/linuxhowto-sl5-nvidiadriverinstallationupdate + misc/linuxloginclusters + misc/loadbalancerllclb1 + misc/nxserverclientinstallation + misc/prepareanewslrelease + misc/projectpsi-puppet1 + misc/psi-puppet2_installation + misc/puppetmanifestsforsl53 + misc/puppetmasteratpsi + misc/puppet-trouble-shooting-in-twiki + misc/release_snapshotssl53 + misc/repairrpmdb + misc/sap_client_for_linux_howto + misc/updatesl57 + misc/updateslmaindoc + misc/vpnclientlinux diff --git a/admin-guide/legacy/misc/afstowindowsloginchangeinsl4andsl5.rst b/admin-guide/legacy/misc/afstowindowsloginchangeinsl4andsl5.rst new file mode 100644 index 00000000..d09a3775 --- /dev/null +++ b/admin-guide/legacy/misc/afstowindowsloginchangeinsl4andsl5.rst @@ -0,0 +1,199 @@ +AFS to Windows-Login Change +=========================== + +References +---------- + +http://ait.web.psi.ch/services/linux/news/unified_login1.html + +Introduction +------------ + +In the night from August 2 to 3 2009 the AFS authentication service +will be changed to the Windows authentication service on Green SL4 and +SL5 PCs. + +This document describes the changes that have to be made in our +cfengine and puppet environments to facilitate the PSI wide automatic +reconfiguration of the Kerberos 5 authentication service on Green SL4 +and SL5 systems. + +This automatic reconfiguration requires cfengine running on SL4 and +puppet running on SL5 hosts respectively. + +Note: For technical reasons SL3 systems can not use the Windows +authentication service. + +Basically, the following two steps have to be performed: + +- Replace the current `krb5.conf` for the AFS authentication service by + the new `krb5.conf` for the Windows authentication service. + +- Distribute the `krenew.sh` script, which periodically renews an + existing renewable ticket. It starts running when the user logs in + to its graphical desktop. + + +For additional information see the reference. + +Files +----- + +`/etc/krb5.conf` for the Windows authentication server for SL4 and +SL5:: + + [libdefaults] + default_realm = D.PSI.CH + ticket_lifetime = 25h + dns_lookup_realm = false + dns_lookup_kdc = false + udp_preference_limit = 10 + renew_lifetime = 30d + forwardable = true + + [realms] + PSI.CH = { + kdc = afs00.psi.ch:88 afs01.psi.ch:88 afs02.psi.ch:88 + admin_server = afs00.psi.ch:749 + kpasswd_server = afs00.psi.ch:464 + default_domain = psi.ch + } + D.PSI.CH = { + kdc = d.psi.ch. + kpasswd_server = d.psi.ch. + default_domain = psi.ch + } + [domain_realm] + .psi.ch = D.PSI.CH + + +To automatically renew a Kerberos v5 ticket during an X session the +krenew command will be started when logging in to X. It is executed by +the script `krenew.sh`, which is placed into +`/etc/X11/xinit/xinitrc.d/`. + +`/etc/X11/xinit/xinitrc.d/krenew.sh` for SL4 and SL5:: + + #!/bin/bash + + /usr/bin/krenew -b -K 60 -t + + +Procedure +--------- + +SL4 +~~~ + +Replace `krb5.conf` File by Cfengine +.................................... + +The replacement of the `krb5.conf` is done by cfengine +on Green SL4 systems. + +The current `krb5.conf` source files:: + + /afs/psi.ch/service/linux/cfengine/masterfiles/distTesting/scientific/46/etc/krb5.conf + +and:: + + /afs/psi.ch/service/linux/cfengine/masterfiles/dist/scientific/46/etc/krb5.conf + +have to be replaced by the `krb5.conf` file for the Windows +authentication server. + + +Distribute `krenew.sh` By Cfengine +.................................. + +Copy `krenew.sh` to:: + + /afs/psi.ch/service/linux/cfengine/masterfiles/distTesting/scientific/46/etc/ + +and:: + + /afs/psi.ch/service/linux/cfengine/masterfiles/dist/scientific/46/etc/ + + +Configure cfengine to distribute them by adding the following entry to:: + + /afs/psi.ch/service/linux/cfengine/masterfiles/inputsTesting/scientific/46/cf.linux.AFS + +and:: + + /afs/psi.ch/service/linux/cfengine/masterfiles/inputs/scientific/46/cf.linux.AFS + + +The entry:: + + linux.scientific:: + $(MASTERDIR)/$(DISTDIR)/$(DIST)/$(RELEASE)/etc/krenew.sh + owner=root group=root + mode=0755 + dest=/etc/X11/xinit/xinitrc.d/krenew.sh + type=sum # makes a MD5 checksum + server=$(MASTERHOST) + backup=true + syslog=true + + +SL5 +--- + +Replace `krb5.conf` File by Puppet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The replacement of the `krb5.conf` is done by puppet on Green SL5 +systems. + +The corresponding `krb5.conf` source file:: + + /afs/psi.ch/software/linux/dist/scientific/51/puppet/files/afs/etc/krb5.conf + +has to be replaced by the `krb5.conf` file for the Windows +authentication server. + +Distribute `krenew.sh` By Puppet +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Copy `krenew.sh` to the following puppet directory:: + + /afs/psi.ch/software/linux/dist/scientific/51/puppet/files/afs/etc/ + +Now edit the puppet manifest `psi_afs.pp` in both environments, +production development. Add `krenew.sh` to the file resource type as +shown below. + +`/afs/psi.ch/service/linux/puppet/etc/puppet/development/manifests/psi_defaults/psi_afs.pp`, + +`/afs/psi.ch/service/linux/puppet/etc/puppet/production/manifests/psi_defaults/psi_afs.pp`:: + + # psi_afs.pp + # + # Link to PSI pam files + # Default PAM configuration for PSI systems + # + + + class psi_afs { + + file { + "/etc/krb5.conf": + owner => "root", + group => "root", + source => [ + "puppet://$servername/$psi_release/afs/etc/krb5.conf.$hostname", + "puppet://$servername/$psi_release/afs/etc/krb5.conf" + ]; + + "/etc/X11/xinit/xinitrc.d/krenew.sh": + owner => "root", + group => "root", + mode => "755", + source => [ + "puppet:///$psi_release/afs/etc/krenew.sh.$hostname", + "puppet:///$psi_release/afs/etc/krenew.sh" + ]; + } + + } diff --git a/admin-guide/legacy/misc/configureldaponpsipuppet3.rst b/admin-guide/legacy/misc/configureldaponpsipuppet3.rst new file mode 100644 index 00000000..de945ec5 --- /dev/null +++ b/admin-guide/legacy/misc/configureldaponpsipuppet3.rst @@ -0,0 +1,110 @@ +Configure LDAP on `psi-puppet3` +=============================== + +References +---------- + +- https://intranet.psi.ch/AIT/LdapActiveDirectoryIntegrationPSI + +- http://linux.web.cern.ch/linux/docs/account-mgmt.shtml + + +Introduction +------------ + +This document describes the configuration of LDAP to access user account +information on an SL6 system. + +Requirements +------------ + +RPMS: + +- nss-pam-ldapd + +Procedure +--------- + +Configure `/etc/nsswitch.conf` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `/etc/nsswitch.conf` configuration file describes the order in +which password-file lookups are performed. To make sure that local +accounts take precedence over LDAP accounts, it should have these +entries:: + + passwd: files ldap + shadow: files + group: files ldap + + +Configuring `/etc/nslcd.conf` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The `/etc/nslcd.conf` configuration file is used to set system-wide +defaults to be applied when running ldap clients. This mechanism is +available on SLP6. + +This section describes the options that are relevant to configure +account lookups in the d.psi.ch LDAP service. An example configure +file containing the options described below is shown here. Please edit +it to suit your needs - in particular the `filter passwd` entry!:: + + + # the ldaps uri enforces SSL + uri ldaps://d.psi.ch:636 + base ou=PSI,dc=d,dc=psi,dc=ch + binddn CN=linux_ldap,OU=Services,OU=IT,DC=d,DC=psi,DC=ch + bindpw *NOT SHOWN* + + # ldap base definitions for each nameservice + base passwd ou=Users,ou=PSI,dc=d,dc=psi,dc=ch + base group ou=Groups,ou=PSI,dc=d,dc=psi,dc=ch + + + filter passwd (&(objectClass=user)(!(objectClass=computer))(msSFU30UidNumber=*)(msSFU30HomeDirectory=*)) + map passwd uid cn + map passwd uidNumber msSFU30UidNumber + map passwd gidNumber msSFU30GidNumber + map passwd loginShell msSFU30LoginShell + map passwd gecos displayName + # do not resolve the unneeded userPassword + #map passwd userPassword msSFU30Password + + map passwd homeDirectory msSFU30HomeDirectory + # for our clusters' special environments we may want to use an expression + # #map passwd homeDirectory "/home/${sAMAccountName}" + + filter group (&(objectClass=Group)(msSFU30Name=*)) + map group uniqueMember member + map group gidNumber msSFU30GidNumber + + timelimit 30 + + # we may want to use this to reduce standing connections to the LDAP server + idle_timelimit 300 + + # require that server's certificate is tested. The standard installed CA bundle includes + # the necessary Root CA cert from QuoVadis + tls_reqcert hard + tls_cacertfile /etc/ssl/certs/ca-bundle.crt + + # request paged results from the LDAP server + pagesize 1000 + + referrals off + + +Please make sure that the `nss-pam-ldapd` RPM is installed on your +client machine. Run `yum install nss-pam-ldapd` if this RPM is not +installed. + +Then, make sure that the `nslcd` runs, and gets started at boot time:: + + /sbin/service nslcd restart + /sbin/chkconfig --level 345 nslcd on + + +Note: the `nslcd` service must be restarted after changes to the +`/etc/nslcd.conf` have been made! For more information, run `man +nslcd.conf` and/or `man nslcd`. diff --git a/admin-guide/legacy/misc/createanewkickstartinstallationforfedora10.rst b/admin-guide/legacy/misc/createanewkickstartinstallationforfedora10.rst new file mode 100644 index 00000000..2de385a5 --- /dev/null +++ b/admin-guide/legacy/misc/createanewkickstartinstallationforfedora10.rst @@ -0,0 +1,119 @@ +Create a new Kickstart Installation (for Fedora 10) +=================================================== + +This document describes the setup of a new kickstart installation at +PSI taking Fedora10 as an example. + + +Introduction +~~~~~~~~~~~~ + +Some NICs include the ability to boot using a Pre-Execution +Environment (PXE). It works by sending out a broadcast request for a +DHCP server on the network. If the DHCP server is configured to send +the client the IP address or hostname of a tftp server and the +location on that tftp server of the files needed to start the Linux +installation, the client can start a network installation without +having to boot from local media such as a CD. + +This method can also be used with kickstart to perform an automated +network installation. + +To perform a network installation using PXE boot, use the following +steps: + +- Create an installation tree for the network install and make it + available to the systems being installed. + +- Configure the tftp server. + +- Configure the DHCP server. + +- Boot the system to start the installation. + + +Procedure +~~~~~~~~~ + +Preparation of the PXE Boot Installation +........................................ + +Go to the `tftp` top directory:: + + # cd /afs/psi.ch/service/linux/tftpboot/ + # cd pxelinux.cfg/ + # cp -a default.testing{,-20081211} + +Now edit the file `default.testing`. Add a new entry for Fedora10. + + # vi default.testing + + # cd .. + # mkdir -p fedora/10 + # cd fedora/10 + # mkdir i386 x86_64 + # cd i386/ + # pwd + /afs/psi.ch/service/linux/tftpboot/fedora/10/i386/ + # wget ftp://sunsite.cnlab-switch.ch/mirror/fedora/linux/releases/10/Fedora/i386/os/isolinux/vmlinuz + # wget ftp://sunsite.cnlab-switch.ch/mirror/fedora/linux/releases/10/Fedora/i386/os/isolinux/initrd.img + + +After having performed a first test installation, the kickstart file +`testhost:/root/anaconda-ks.cfg` based on that installation was +written. This kickstart file was copied to +`/afs/psi.ch/software/linux/kickstart/configs/fedora10-ks.cfg`. Then +`fedora10-ks.cfg` was edited. + +`File: fedora10-ks.cfg Version 1` + +- Note: + + For testing the kickstart installations the root password is given, + see line starting with `rootpw`. In the final version it will be + removed:: + + + ################################## + # fedora10-ks.cfg 32-bit + ################################## + + install + url --url=ftp://sunsite.cnlab-switch.ch/mirror/fedora/linux/releases/10/Fedora/i386/os + lang en_US.UTF-8 + + network --device eth0 --bootproto dhcp + rootpw --iscrypted $6$dzHkd6Tb5OuEd92w$1mFgHdoRA9JnIeTz7lq8tvh8Gu1DJPWQyV7LyLGGTEE27ORgF6rYLPDc5nRZRMzoX8Zpasg5UFy4T7jOYyWa50 + authconfig --enableshadow --passalgo=sha512 + selinux --disabled + timezone --utc Europe/Zurich + bootloader --location=mbr + + ### PARTITION + # The following is the partition information you requested + # Note that any partitions you deleted are not expressed + # here so unless you clear all partitions first, this is + # not guaranteed to work + #part /boot --fstype ext3 --size=100 --asprimary + #part swap --size=500 --asprimary + #part / --fstype ext3 --size=200 --grow --asprimary + + %packages + @admin-tools + @base + @core + @editors + @hardware-support + @text-internet + + %end + + +Kickstart Pre Installation Scripts: + +- /afs/psi.ch/software/linux/dist/scientific/5/kickstart/pre +- /afs/psi.ch/software/linux/dist/scientific/5/kickstart/pre/set_partition +- /afs/psi.ch/software/linux/dist/scientific/5/kickstart/pre/pre_custom +- /afs/psi.ch/software/linux/dist/scientific/5/kickstart/pre/ask_ip +- /afs/psi.ch/software/linux/dist/scientific/5/kickstart/pre/pre_custom +- /afs/psi.ch/software/linux/dist/scientific/5/kickstart/pre/ask_ipaddr diff --git a/admin-guide/legacy/misc/disklessclientsl60.rst b/admin-guide/legacy/misc/disklessclientsl60.rst new file mode 100644 index 00000000..e8d36572 --- /dev/null +++ b/admin-guide/legacy/misc/disklessclientsl60.rst @@ -0,0 +1,54 @@ +Diskless Client SL60 +==================== + +Procedure +--------- + +Select the kernel that diskless clients should use +(vmlinuz-kernel-version) and copy it to the tftp boot directory:: + + # cp /boot/vmlinuz-2.6.32-220.4.1.el6.i686 /afs/psi.ch/service/linux/tftpboot/dl/sl60/i386/ + + +Create the initrd (i.e. initramfs-kernel-version.img) with network support:: + + # yum install dracut-network + # dracut initramfs-dl-2.6.32-220.4.1.el6.i686.img 2.6.32-220.4.1.el6.i686 + + +Copy the resulting initramfs-kernel-version.img into the tftp boot directory as well:: + + # cp /tmp/initramfs-dl-2.6.32-220.4.1.el6.i686.img /afs/psi.ch/service/linux/tftpboot/dl/sl60/i386/ + +Edit the default boot configuration to use the initrd and kernel +inside `/var/lib/tftpboot`. This configuration should instruct the +diskless client's root to mount the exported file system +(`/exported/root/directory`) as read-write. To do this, configure +`/var/lib/tftpboot/pxelinux.cfg/default` with the following:: + + label sl6dl + kernel dl/sl60/i386/vmlinuz-2.6.32-220.4.1.el6.i686 + append initrd=dl/sl60/i386/initramfs-dl-2.6.32-220.4.1.el6.i686.img root=nfs4:129.129.190.91:/dl/sl60/i386/base rw + + +Replace server-ip with the IP address of the host machine on which the +tftp and DHCP services reside. The NFS share is now ready for +exporting to diskless clients. These clients can boot over the network +via PXE. + +From the manual:: + + 22.3. Configuring an Exported File System for Diskless Clients + The root directory of the exported file system (used by diskless clients in the network) is shared via NFS. Configure the NFS service to export the root directory by adding it to /etc/exports. For instructions on how to do so, refer to Section 12.7.1, “ The /etc/exports Configuration File”. + To accommodate completely diskless clients, the root directory should contain a complete Red Hat Enterprise Linux installation. You can synchronize this with a running system via rsync, as in: + # rsync -a -e ssh --exclude='/proc/*' --exclude='/sys/*' hostname.com:/ /exported/root/directory + Replace hostname.com with the hostname of the running system with which to synchronize via rsync. The /exported/root/directory is the path to the exported file system. + Alternatively, you can also use yum with the --installroot option to install Red Hat Enterprise Linux to a specific location. For example: + yum groupinstall Base --installroot=/exported/root/directory + The file system to be exported still needs to be configured further before it can be used by diskless clients. To do this, perform the following procedure: + Procedure 22.2. Configure file system + Configure the exported file system's /etc/fstab to contain (at least) the following configuration: + none /tmp tmpfs defaults 0 0 + tmpfs /dev/shm tmpfs defaults 0 0 + sysfs /sys sysfs defaults 0 0 + proc /proc proc defaults 0 0 diff --git a/admin-guide/legacy/misc/dkmsbasics.rst b/admin-guide/legacy/misc/dkmsbasics.rst new file mode 100644 index 00000000..491a9730 --- /dev/null +++ b/admin-guide/legacy/misc/dkmsbasics.rst @@ -0,0 +1,396 @@ +Dynamic Kernel Module Support (DKMS) Basics +=========================================== + +References +---------- + +G. Lerhaupt, Linuxjournal (www.linuxjournal.com/), September 1st, 2003. + + +Introduction To DKMS +-------------------- + +Source is a wonderful thing. Merged module source in the kernel tree +is even better. Most of all, support for that source is what really +counts. In today's explosion of Linux in the enterprise, the ability +to pick up the phone and find help is critical. More than ever, +corporations are driving Linux development and requirements. Often, +this meets with skepticism and a bit of anxiety by the community, but +if done correctly, the benefits are seen and felt by everyone. + +The dynamic kernel module support (DKMS) framework should be viewed as +a prime example of this. DKMS, a system designed to help Dell Computer +Corporation distribute fixes to its customers in a controlled fashion, +also speeds driver development, testing and validation for the entire +community. + +The DKMS framework is basically a duplicate tree outside of the kernel +tree that holds module source and compiled module binaries. This +duplication allows for a decoupling of modules from the kernel, which, +for Linux solution and deployment providers, is a powerful tool. The +power comes from permitting driver drops onto existing kernels in an +orderly and supportable manner. In turn, this frees both providers and +their customers from being bound by kernel drops to fix their issues. +Instead, when a driver fix has been released, DKMS serves as a stopgap +to distribute the fix until the code can be merged back into the +kernel. + +Staying with the customer angle for a bit longer, DKMS offers other +advantages. The business of compiling from source, installing or +fidgeting with rebuildable source RPMs has never been for the +faint-of-heart. The reality is that more Linux users are coming in +with less experience, necessitating simpler solutions. DKMS bridges +these issues by creating one executable that can be called to build, +install or uninstall modules. Further, using its match feature, +configuring modules on new kernels could not be easier, as the modules +to install can be based solely on the configuration of some kernel +previously running. In production environments, this is an immense +step forward as IT managers no longer have to choose between some +predefined solution stack or the security enhancements of a newer +kernel. + +DKMS also has much to offer developers and veteran Linux users. The +aforementioned idea of the decoupling of modules from the kernel +through duplication (not complete separation) creates a viable test +bed for driver development. Rather than having to push fixes into +successive kernels, these fixes can be distributed and tested on the +spot and on a large scale. This speedup in testing translates to an +overall improvement in the speed of general development. By removing +kernel releases as a blocking mechanism to widespread module code +distribution, the result is better tested code that later can be +pushed back into the kernel at a more rapid pace—a win for both +developers and users. + +DKMS also makes developers' lives easier by simplifying the delivery +process associated with kernel-dependent software. In the past, for +example, Dell's main method for delivering modules was RPMs containing +kernel-specific precompiled modules. As kernel errata emerged, we +often were taken through the monotonous and unending process of +recompiling binaries for these new kernels—a situation that no +developer wants to be in. However, Dell still favored this delivery +mechanism because it minimized the amount of work and/or knowledge +customers needed to have to install modules. With DKMS, we can meet +these usability requirements and significantly decrease our workload +from the development standpoint. DKMS requires module source code to +be located only on the user's system. The DKMS executable takes care +of building and installing the module for any kernel users may have on +their systems, eliminating the kernel catch-up game. + + +Using DKMS +---------- + +With all of this up-front hype about DKMS, perhaps it might be best to +settle into the particulars of actually how the software is used. + +- Using DKMS for a module requires that the module source be located + on the user's system and that it be located in the directory + `/usr/src/(module))-((module-version))/`. + +- A `dkms.conf` file must exist with the appropriately formatted + directives within this configuration file to tell DKMS such things + as where to install the module and how to build it. + +More information on the format of the `dkms.conf` file can be found +later in this article. Once these two requirements have been met and +DKMS has been installed on the system, the user can begin using DKMS +by adding a `module/module-version` to the DKMS tree. The example add +command:: + + # dkms add -m qla2x00 -v v6.04.00 + +would add `qla2x00/v6.04.00` to the extant `/var/dkms` tree. This +command includes creating the directory `/var/dkms/qla2x00/v6.04.00/`, +creating a symlink from `/var/dkms/qla2x00/v6.04.00/source` to +`/usr/src/qla2x00-v6.04.00/` and copying the `dkms.conf` file from its +original location to `/var/dkms/qla2x00/v6.04.00/dkms.conf`. + +Once this add is complete, the module is ready to be built. The `dkms +build` command requires that the proper kernel sources are located on +the system from the `/lib/module/kernel-version/build` symlink. The +make command used to compile the module is specified in the +`dkms.conf` configuration file. Continuing with the `qla2x00/v6.04.00` +example:: + + # dkms build -m qla2x00 -v v6.04.00 -k 2.4.20-8smp + +compiles the module but stops short of installing it. Although build +expects a kernel-version parameter, if this kernel name is left out, +it assumes the currently running kernel. However, building modules +for kernels not currently running also is a viable option. This +functionality is assured through the use of a kernel preparation +subroutine that runs before any module build is performed. This +paranoid kernel preparation involves running a make mrproper, copying +the proper kernel .config file to the kernel source directory, running +a make oldconfig and, finally, running a make dep. These steps ensure +that the module being built is built against the proper kernel +symbols. By default, DKMS looks for the kernel `.config` file in the +`/lib/modules/kernel-version/build/configs/` directory, utilizing Red +Hat's naming structure for those config files. If the kernel `.config` +file is not located in this directory, you must specify a `--config` +option with your build command and tell DKMS where the `.config` file +can be found. + +Successful completion of a build creates, for this example, the +`/var/dkms/qla2x00/v6.04.00/2.4.20-8smp/` directory as well as the log +and module subdirectories within this directory. The log directory +holds a log file of the module make, and the module directory holds +copies of the compiled `.o` binaries. + +With the completion of a build, the module now can be installed on the +kernel for which it was built. Installation copies the compiled module +binary to the correct location in the `/lib/modules/` tree, as +specified in the dkms.conf file. If a module by that name is already +found in that location, DKMS saves it in its tree as an original +module, so it can be put back into place at a later time if the newer +module is uninstalled. The example install command:: + + # dkms install -m qla2x00 -v v6.04.00 -k 2.4.20-8smp + +creates the following symlink:: + + /var/dkms/qla2x00/v6.04.00/kernel-2.4.20-8smp → /var/dkms/qla2x00/v6.04.00/2.4.20-8smp + +This symlink is how DKMS keeps tabs on which driver version is +installed on which kernel. As stated earlier, if a module by the same +name is installed already, DKMS saves a copy in its tree in the +`/var/dkms/module-name/original_module/` directory. In this case, it +would be saved to `/var/dkms/qla2x00/original_module/2.4.20-8smp/`. + +To complete the DKMS cycle, you also can uninstall or remove your +module from the tree. Uninstall removes the module you installed and, +if applicable, replaces it with its original module. In scenarios +where multiple versions of a module are located within the DKMS tree, +when one version is uninstalled, DKMS does not try to understand or +assume which of these other versions should be put in its +place. Instead, if a true original_module was saved from the original +DKMS installation, it is put back into the kernel. All of the other +module versions for that module are left in the built state. An +example uninstall would be:: + + # dkms uninstall -m qla2x00 -v v6.04.00 -k 2.4.20-8smp + +If the kernel version parameter is unset, the currently running kernel +is assumed, but the same behavior does not occur with the remove +command. Remove and uninstall are similar in that a remove command +completes all of the same steps as does an uninstall. However, if the +module-version being removed is the last instance of that +module-version for all kernels on your system, after the uninstall +portion of the remove completes, remove physically removes all traces +of that module from the DKMS tree. In other words, when an uninstall +command completes, your modules are left in the **built** +state. However, when a remove completes, you have to start over from +the add command before you can use this module again with DKMS. Here +are two sample remove commands:: + + # dkms remove -m qla2x00 -v v6.04.00 -k 2.4.20-8smp + + # dkms remove -m qla2x00 -v v6.04.00 --all + +With the first remove command, the module would be uninstalled. If +this `module/module-version` were not installed on any other kernel, +all traces of it would be removed from the DKMS tree. If, say, +`qla2x00/v6.04.00` also was installed on the `2.4.20-8bigmem` kernel, +the first remove command would leave it alone—it would remain intact +in the DKMS tree. That would not be the case in the second example. It +would uninstall all versions of the `qla2x00/v6.04.00` module from all +kernels and then completely expunge all references of +`qla2x00/v6.04.00` from the DKMS tree. Thus, remove is what cleans +your DKMS tree. + + +Miscellaneous DKMS Commands +--------------------------- + +DKMS also comes with a fully functional status command that returns +information about what is currently located in your tree. If no +parameters are set, it returns all information found. Logically, the +specificity of information returned depends on which parameters are +passed to your status command. Each status entry returned is of the +state added, built or installed. If an original module has been saved, +this information also is displayed. Some example status commands +include:: + + # dkms status + + # dkms status -m qla2x00 + + # dkms status -m qla2x00 -v v6.04.00 + + # dkms status -k 2.4.20-8smp + + # dkms status -m qla2x00 -v v6.04.00 -k 2.4.20-8smp + + +Another major feature of DKMS is the match command. The match command +takes the configuration of DKMS-installed modules for one kernel and +applies it to some other kernel. When the match completes, the same +`module/module-versions` installed for one kernel are then installed +on the other kernel. This is helpful when you are upgrading from one +kernel to the next but want to keep the same DKMS modules in place for +the new kernel. In the example:: + + # dkms match --templatekernel 2.4.20-8smp -k 2.4.20-9smp + +`--templatekernel` is the match-er kernel from which the configuration +is based. The `-k` kernel is the match-ee upon which the +configuration is instated. + +For systems management purposes, the commands mktarball and ldtarball +also have been added to DKMS. These commands allow the user to make +and load tarball archives, respectively, into the DKMS tree to +facilitate using DKMS in deployments where many similar systems +exist. This allows the system administrator to build modules on only +one system. Rather than build the same module on every other system, +the built binary can be applied directly to the other systems' DKMS +tree. Specifically, mktarball creates a tarball of the source for a +given `module/module-version`. It then archives the DKMS tree of every +kernel version that has a module built for that +`module/module-version`. Consider the example:: + + # dkms mktarball -m qla2x00 -v v6.04.00 -k 2.4.20-8smp,2.4.20-8 + +Depending on the `-k` kernel parameter, `mktarball` archives only +certain binaries compiled for those kernels specified. If no kernel +parameter is given, it archives all built module binaries for that +`module/module-version`. + +With `ldtarball`, DKMS simply parses the archive created with +mktarball and applies whatever is found to that system's DKMS +tree. This leaves all modules in the built state; the `dkms install` +command then can be used to place the module binaries into the +`/lib/modules` tree. Under normal operation, ldtarball does not +overwrite any files that already exist in the system's DKMS +tree. However, the archive can be forced over what is in the tree with +the `--force` option. An example `ldtarball`:: + + # dkms ldtarball --config qla2x00-v6.04.00-kernel2.4.20-8smp.tar.gz + +The last miscellaneous DKMS command is `mkdriverdisk`. As can be +inferred from its name, `mkdriverdisk` takes the proper sources in +your DKMS tree and creates a driver disk image that can provide +updated drivers to Linux distribution installations. A sample +`mkdriverdisk` might look like:: + + # dkms mkdriverdisk -d redhat -m qla2x00 -v v6.04.00 -k 2.4.20-8BOOT + +Currently, the only supported distribution driver disk format is Red +Hat, but this easily could expand with some help from the community in +understanding driver disk requirements and formats on a +per-distribution basis. For more information on the extra necessary +files and their formats for DKMS to create Red Hat driver disks, see +`people.redhat.com/dledford`. These files should be placed in your +module source directory. + +The dkms.conf Configuration File Format +--------------------------------------- + +For maintainers of DKMS packages, the `dkms.conf` configuration file +is the only auxiliary piece necessary to make your source tarball +DKMS-ready. The format of the conf file is a successive list of shell +variables sourced by DKMS when working with your package. For +example, an excerpt from the `qla2x00/v6.04.00 dkms.conf` file:: + + MAKE="make all INCLUDEDIR=/lib/modules/$kernelver/build/include" + MAKE_smp="make SMP=1 all INCLUDEDIR=/lib/modules/$kernelver/build/include" + LOCATION="/kernel/drivers/addon/qla2200" + REMAKE_INITRD="yes" + MODULE_NAME="qla2200.o:qla2200_6x.o qla2300.o:qla2300_6x.o" + CLEAN="make clean" + MODULES_CONF_ALIAS_TYPE="scsi_hostadapter" + MODULES_CONF0="options scsi_mod scsi_allow_ghost_devices=1" + +shows that each of the shell variable directives should be coded in +all capital letters. One of the current exceptions to this rule is the +`MAKE_` directive. DKMS uses the generic `MAKE=` command to build your +module. But, if a `MAKE_kernel-regexp-text` command exists and the +text after the `MAKE_ matches` (as a substring) the kernel for which +it is being built, then this alternate make command is used. In the +above example, you can see how DKMS would use the `MAKE_smp` directive +on any smp kernel for which it was building this module. Similar +`PATCH_` commands also exist. When the text after the underscore +matches the kernel for which a module is being built, that patch first +is applied to the module source. This allows developers to distribute +one source tarball, with one `dkms.conf` and multiple patches. Yet, +different patches can be applied as necessary to the source to ensure +all modules function correctly on all kernels. + +Also notice that dkms.conf accepts the `$kernelver` variable, which, +at build time, is replaced with the kernel version for which the +module is being built. This is especially important so the correct +include directories are referenced when compiling a module for a +kernel that is not currently running. + +Using DKMS in Conjunction with RPM +---------------------------------- + +DKMS and RPM actually work quite well together. The only twist is that +to make it function properly, you have to create an RPM that installs +source. Although normal practice is to install source only with source +RPMs, a source RPM does not necessarily work with DKMS; it will not +let you do much besides install the source. Instead, your source +tarball needs to be included with your RPM, so your source can be +placed in `/usr/src/module-module-version/` and the proper DMKS +commands can be called. The `%post` and `%preun` basically are DKMS +commands. + +Here is a sample `.spec` file:: + + %define module qla2x00 + + Summary: Qlogic HBA module + Name: %module_dkms + Version: v6.04.00 + Release: 1 + Vendor: Qlogic Corporation + Copyright: GPL + Packager: Gary Lerhaupt + Group: System Environment/Base + BuildArch: noarch + Requires: dkms gcc bash sed + Source0: qla2x00src-%version.tgz + Source1: dkms.conf + BuildRoot: %{_tmppath}/%{name}-%{version}-%{release}-root/ + + %description + This package contains Qlogic's qla2x00 HBA module meant + for the DKMS framework. + + %prep + rm -rf qla2x00src-%version + mkdir qla2x00src-%version + cd qla2x00src-%version + tar xvzf $RPM_SOURCE_DIR/qla2x00src-%version.tgz + + %install + if [ "$RPM_BUILD_ROOT" != "/" ]; then + + rm -rf $RPM_BUILD_ROOT + fi + mkdir -p $RPM_BUILD_ROOT/usr/src/%module-%version/ + install -m 644 $RPM_SOURCE_DIR/dkms.conf + $RPM_BUILD_ROOT/usr/src/%module-%version + install -m 644 qla2x00src-%version/* + $RPM_BUILD_ROOT/usr/src/%module-%version + + %clean + if [ "$RPM_BUILD_ROOT" != "/" ]; then + + rm -rf $RPM_BUILD_ROOT + fi + + %files + %defattr(0644,root,root) + %attr(0755,root,root) /usr/src/%module-%version/ + + %pre + + %post + /sbin/dkms add -m %module -v %version + /sbin/dkms build -m %module -v %version + /sbin/dkms install -m %module -v %version + exit 0 + + %preun + /sbin/dkms remove -m %module -v %version --all + exit 0 diff --git a/admin-guide/legacy/misc/firefoxpreferenceshowto.rst b/admin-guide/legacy/misc/firefoxpreferenceshowto.rst new file mode 100644 index 00000000..fbb4f84f --- /dev/null +++ b/admin-guide/legacy/misc/firefoxpreferenceshowto.rst @@ -0,0 +1,4 @@ +Firefox Preferences +=================== + +`/usr/lib64/firefox/browser/defaults/preferences/all-psi.js` diff --git a/admin-guide/legacy/misc/howto-start-vncserver.rst b/admin-guide/legacy/misc/howto-start-vncserver.rst new file mode 100644 index 00000000..04283d6c --- /dev/null +++ b/admin-guide/legacy/misc/howto-start-vncserver.rst @@ -0,0 +1,18 @@ +How To Start Vncserver +====================== + +Login to the remote host:: + + # ssh root@ + # ls -l /tmp/krb* + +Login as you want to get the Desktop from:: + + # su - + # export KRB5CCNAME=/tmp/krb5cc_3651_bxD3lb + # aklog + # x0vncserver -SecurityTypes=None -display=:0.0 + +Start vnc client on local host:: + + # vncviewer diff --git a/admin-guide/legacy/misc/howtoeditinstallimg.rst b/admin-guide/legacy/misc/howtoeditinstallimg.rst new file mode 100644 index 00000000..fe82f43e --- /dev/null +++ b/admin-guide/legacy/misc/howtoeditinstallimg.rst @@ -0,0 +1,20 @@ +How to edit `install.img` +========================= + +Introduction +------------ + +This HowTo describes how to extract, edit and rebuild the install.img +file of an SL6 release. This file is found in the distribution +toplevel `$basearch` directory e.g. in +`/afs/psi.ch/software/linux/dist/scientific/62/x86_64/images/` at our +site. It is loaded during the installation and brings up the +installation process. + +The reason to edit the `install.img` in this example is the file +`/etc/anaconda.repos.d/sl.repo`, which references the original SL repos, +i.e. the anaconda installer will try to get RPMS from these external +repos during the installation even if we declare our local repos in +the kickstart config file. We want now that anaconda takes RPMS from +our local copies of the SL repos, because first the installation is +faster, second we do not depend on down times of the SL site. diff --git a/admin-guide/legacy/misc/kernelmodulee1000eupdateforsl5.1.rst b/admin-guide/legacy/misc/kernelmodulee1000eupdateforsl5.1.rst new file mode 100644 index 00000000..27b3d0ec --- /dev/null +++ b/admin-guide/legacy/misc/kernelmodulee1000eupdateforsl5.1.rst @@ -0,0 +1,864 @@ +Kernel Module E1000E Update For SL5.1 +===================================== + +This document is almost certainly obsolete, hence I just include the +unformatted POD source of the original:: + + =head2 References + + =over 4 + + =item * + + http://support.intel.com/support/ + + =back + + =head2 Introduction + + The Intel Gigabit ethernet card F<82567LM>, which comes with the + new Fujitsu Siemens computers F, F, + F and F, contemporary does not work + out of the box in SL51 (and for sure others) because the updated version + of the e1000e driver is not available yet in Scientific Linux. + + As a consequence of this the network installation is not working for this + kind of hardware, because + the SL5.1 installation kernel, too, is not coming with the proper driver. + + This documents describes a quick workaround, Solution 1, and a more profound + procedure, Solution 2, to solve this issue. A third alternative, Solution 3, + is shortly mentioned, but could not be finalized. + + =head3 Solution 1 + + For the network installation + via PXE boot a second SL5 compatible network card has to be plugged in. When the + installation has finished, an updated version of the + e1000e driver, that supports the mentioned hardware can be downloaded + from the Intel website (see References) and installed on the system. + + =head3 Solution 2 + + Use the SL5.3 kernel, the e1000e driver of which does support the F<82567LM> hardware, + to install the SL5.1. + + First, the PXE boot environment has to be setup with the SL5.3 kernel and the related + initial ramdisk. + + Second, the F<.buildstamp> in the initial ramdisk of SL5.3 has to be replaced by the + F<.buildstamp> of SL5.1. This facilitates the SL5.3 installer to use the SL5.1 installation + tree. Therefore the ramdisk has to be unpacked, modified and + repacked (it is a gzipped cpio archive). + + Third, build a kernel module e1000e RPM for SL5.1 which will be installed during the SL5.1 + installation by means of a custom key F. + + Fourth, setup the F custom key. + + =head3 Solution 3 + + Note: This was tried but does not work yet. + + For the network installation compile the new e1000e driver for the installation kernel and put it into + the corresponding initial ramdisk. + + For the running system build the e1000e RPMS for the current kernel/architecture combinations + and install the RPMS during the kickstart process. + + When the kernel is updated the corresponding e1000e RPMS have to be rebuilt and put into + the update repository. + + =head2 Procedure for Solution 1 + + Get the tarball, extract it and build the driver following + the instructions in the README of the tarball. + + Get the tarball and extract it. + + # [root@pc7637] + # uname -a + Linux pc7637 2.6.18-92.1.22.el5PAE #1 SMP Tue Dec 16 07:10:07 EST 2008 i686 i686 i386 GNU/Linux + # cd /tmp/ + # wget http://downloadmirror.intel.com/17069/eng/e1000e-0.4.1.7.tar.gz + # tar xfz e1000e-0.4.1.7.tar.gz + + Install the corresponding kernel source RPM. + + # rpm -ivh /afs/psi.ch/software/mirror/scientific/5x/SRPMS/vendor/kernel-2.6.18-92.1.22.el5.src.rpm + + Build the RPM for the running kernel. + + # rpmbuild -tb e1000e-0.4.1.7.tar.gz + ... + Wrote: /usr/src/redhat/RPMS/i386/e1000e-0.4.1.7-1.i386.rpm + ... + + Install the driver RPM. + + # rpm -ivh /usr/src/redhat/RPMS/i386/e1000e-0.4.1.7-1.i386.rpm + + Becaus this is a newly installed host, disable older kernels in grub, + because the kernel module e1000e is only valid for the running kernel. + However the older kernels should be removed later, if there are no needs to run + them. + + # vi /boot/grub/grub.conf + + The resulting RPM e1000e-0.4.1.7-1.i386.rpm was built on a FS Celsius W370 + after Network installation via an old plugged in 3COM network card + as 2nd network device. After installation of this RPM the 3COM + card was removed and the on board Intel Gigabit network card + was running with the new e1000e kernel module. + + =over 4 + + =item Note: + + This RPM contains only the module for an SL51 PAE kernel. + + /lib/modules/2.6.18-92.1.22.el5PAE/kernel/drivers/net/e1000e/e1000e.ko.new + + =back + + =for comment + ##################################################################################3 + + =head2 Procedure for Solution 2 + + =head3 Setup the PXE Boot Environment for the New Kickstart Installation + + Add the following labels to + F. + At the time of writing they are used for testing, their names will probably + be changed later on. + + Note: You can take the same kickstart configuration files as for the default + SL51 installation, under the labels sl5 and sl564. + + label sl53t32 + kernel scientific/53for51install/i386/vmlinuz + append initrd=scientific/53for51install/i386/initrd.img ksdevice=eth0 \ + ks=nfs:129.129.190.59:/master/linux/kickstart/configs/sl51-a-ks.cfg noipv6 + + label sl53t64 + kernel scientific/53for51install/x86_64/vmlinuz + append initrd=scientific/53for51install/x86_64/initrd.img ksdevice=eth0 \ + ks=nfs:129.129.190.59:/master/linux/kickstart/configs/sl51-64-a-ks.cfg noipv6 + + Copy the installation kernel and the initial ramdisk to the tftpboot + location given in the respective labels above. + + # cd /afs/psi.ch/service/linux/tftpboot/scientific/ + # mkdir -p 53for51install/i386 53for51install/x86_64 + + # cd 53for51install/i386/ + # wget http://ftp.scientificlinux.org/linux/scientific/5rolling/i386/images/pxeboot/vmlinuz + # wget http://ftp.scientificlinux.org/linux/scientific/5rolling/i386/images/pxeboot/initrd.img + + # cd ../x86_64/ + # wget http://ftp.scientificlinux.org/linux/scientific/5rolling/x86_64/images/pxeboot/vmlinuz + # wget http://ftp.scientificlinux.org/linux/scientific/5rolling/x86_64/images/pxeboot/initrd.img + + Before proceeding with the next section test whether the basic setup is working. + Therefore boot F and F on a test machine. + + This should setup the network connections, start the kickstart + till to the point when it runs the pre installation scripts. + + =head3 Modify the Initial Ramdisk, Example for x86_64 + + Unpack the initial ramdisk image of SL5.3. + + # cd /afs/psi.ch/service/linux/tftpboot/scientific/53for51install/x86_64/ + # mkdir tmp + # cd tmp + # zcat ../initrd.img | cpio -ivd + + The content of the F<.buildstamp> will be something alike. + + # cat .buildstamp + 200902111740.x86_64 + Scientific Linux + 53 + SL + your distribution provided bug reporting tool. + + Now replace this F<.buildstamp> file with the one + of the SL5.1 installation tree. Therefore you also have to + unpack the ramdisk. + + # cd /afs/psi.ch/software/linux/dist/scientific/51/x86_64/images/pxeboot/ + # mkdir tmp + # cd tmp + # zcat ../initrd.img | cpio -ivd + + Here we have the following F<.buildstamp>. + + # cat .buildstamp + 200801141434.x86_64 + Scientific Linux + 51 + SL + your distribution provided bug reporting tool. + + # cp -i .buildstamp \ + # /afs/psi.ch/service/linux/tftpboot/scientific/53for51install/x86_64/tmp/ + + Clean up. + + # cd .. + # rm -rf tmp + + Repack the initial ramdisk of SL5.3 x86_64. + For this part the commands were taken from F of + the SL5.1 RPM F and put into a script, + because repacking the ramdisk without the same command options + as from the F script fails. + + =opentwisty + + # # Function from /sbin/mkinitrd + # findall() { + # echo nash-find "$@" | /sbin/nash --force --quiet + # } + # + # # Architecture + # ARCH="x86_64" + # + # # Set file locations: + # # The temporary directory in the tftpboot directory + # # where the initial ramdisk is extracted to. + # MNTIMAGE="/afs/psi.ch/service/linux/tftpboot/scientific/53for51install/$ARCH/tmp" + # + # # The name of the new ramdisk, not to overwrite the original one + # target="initrd.img_new" + # + # # Start processing + # if test ! -d $MNTIMAGE + # then + # echo "Error: $MNTIMAGE does not exist." + # exit + # fi + # + # if test -e ${MNTIMAGE}/../initrd.img_new.cpio + # then + # echo -n "${MNTIMAGE}/../initrd.img_new.cpio exists. Shall I remove it (y/N)?" + # read a + # if test "$a" = "y" + # then + # rm -f ${MNTIMAGE}/../initrd.img_new.cpio + # fi + # fi + # + # # Create the empty ramdisk file (from /sbin/mkinitrd) + # IMAGE=`mktemp ${MNTIMAGE}/../initrd.img_new.cpio` + # + # # Fill it as cpio archive (from /sbin/mkinitrd) + # (cd $MNTIMAGE; findall . | cpio --quiet -c -o) >| $IMAGE || exit 1 + # + # # Compress the cpio archive (from /sbin/mkinitrd) + # gzip -9 < $IMAGE >| ${MNTIMAGE}/../$target + # + # echo "Check the new initial ramdisk at" + # echo "/afs/psi.ch/service/linux/tftpboot/scientific/53for51install/$ARCH/" + # echo + + =closetwisty + + Go to the tftpboot direcory and setup the new initial ramdisk. + Make also a backup of the original one. + + # cd /afs/psi.ch/service/linux/tftpboot/scientific/53for51install/x86_64/ + # mv initrd.img initrd.img_orig + # ln -s initrd.img_new initrd.img + + Now test the PXE boot kickstart installation using the + label F. + + If everything looks fine clean up and go to the next section + or repeat this part for the i386 architecture. + + # rm -rf tmp/ initrd.img_new.cpio + + =head3 Build the e1000e Kernel Module RPM, Example for x86_64 + + Go to the build system tux50-64 and download the e1000e sources + and get the spec file. + + # [gasser_m@tux50-64] + # cd /scratch/gasser_m/rpm_topdir/SOURCES/ + # wget http://downloadmirror.intel.com/17069/eng/e1000e-0.4.1.7.tar.gz + # tar xfz e1000e-0.4.1.7.tar.gz + # cp e1000e-0.4.1.7/e1000e.spec ../SPECS/ + # rm -rf e1000e-0.4.1.7 + # cd ../SPECS/ + # cp e1000e e1000e_orig + + Note, you can build the RPM directly from this tarball, but here we want to + change the name of the built RPM to apply our PSI naming convention for kernel + modules, thus we need to edit the spec file before building. + + # vi e1000e.spec + + =opentwisty + + #### begin e1000e.spec + + %define driver_name e1000e + %define kernel 2.6.18-92.1.22.el5 + + %define pkg_name kernel-module-%{driver_name}-%{kernel} + + Name: %{pkg_name} + Summary: Intel(R) Gigabit Ethernet Connection + Version: 0.4.1.7 + Release: 1 + Source: %{driver_name}-%{version}.tar.gz + Vendor: Intel Corporation + Packager: Marc Gasser + License: GPL + ExclusiveOS: linux + Group: System Environment/Kernel + Provides: %{driver_name} + URL: http://support.intel.com/support/go/linux/e1000e.htm + BuildRoot: %{_tmppath}/%{driver_name}-%{version}-root + # do not generate debugging packages by default - newer versions of rpmbuild + # may instead need: + #%define debug_package %{nil} + %debug_package %{nil} + # macros for finding system files to update at install time (pci.ids, pcitable) + %define find() %(for f in %*; do if [ -e $f ]; then echo $f; break; fi; done) + %define _pciids /usr/share/pci.ids /usr/share/hwdata/pci.ids + %define _pcitable /usr/share/kudzu/pcitable /usr/share/hwdata/pcitable /dev/null + %define pciids %find %{_pciids} + %define pcitable %find %{_pcitable} + Requires: kernel, fileutils, findutils, gawk, bash + + %description + This package contains the Linux driver for the Intel(R) Gigabit Family of Server Adapters. + + ########################### begin RPM build section + + %prep + %setup -n %{driver_name}-%{version} + + %build + mkdir -p %{buildroot} + + KV=%{kernel} + KA=%{_arch} + KV_BASE=$(echo $KV | sed '{ s/hugemem//g; s/smp//g; s/enterprise//g; }' ) + + if [ -e /usr/src/kernels ] && [ $(echo $KV_BASE | grep "^2.6") ]; then + if [ -e /etc/redhat-release ]; then + KSP=$(ls /lib/modules | grep $KV_BASE) + for K in $KSP ; do + if [ $KA == "x86_64" ] && \ + [ $(echo $K | grep hugemem) ]; then + # Include path for x86_64 hugemem is broken + # on RHEL4 + continue + fi + make -C src clean + make -C src KSP=/lib/modules/$K/build \ + INSTALL_MOD_PATH=%{buildroot} \ + KVERSION=$k \ + MANDIR=%{_mandir} \ + CFLAGS_EXTRA="$CFLAGS_EXTRA" install + done + else + make -C src clean + make -C src INSTALL_MOD_PATH=%{buildroot} \ + MANDIR=%{_mandir} install + fi + else + SwitchRHKernel () { + CFLAGS_EXTRA="" + for K in $2 ; do + if [ $K == $1 ] ; then + CFLAGS_EXTRA="$CFLAGS_EXTRA -D__BOOT_KERNEL_$K=1" + else + CFLAGS_EXTRA="$CFLAGS_EXTRA -D__BOOT_KERNEL_$K=0" + fi + done + } + + KSP="/lib/modules/$KV/build + /usr/src/linux-$KV + /usr/src/linux-$(echo $KV | sed 's/-.*//') + /usr/src/kernel-headers-$KV + /usr/src/kernel-source-$KV + /usr/src/linux-$(echo $KV | sed 's/\([0-9]*\.[0-9]*\)\..*/\1/') + /usr/src/linux" + + KSRC=$(for d in $KSP ; do [ -e $d/include/linux ] && echo $d; echo; done) + KSRC=$(echo $KSRC | awk '{ print $1 }') + + if [ -e $KSRC/include/linux/rhconfig.h ] ; then + RHKL=$(grep 'BOOT_KERNEL_.* [01]' /boot/kernel.h | + sed 's/.*BOOT_KERNEL_\(.*\) [01]/\1/') + if echo $RHKL | grep BIGMEM + then + RHKL=$(echo $RHKL | sed 's/ENTERPRISE//') + fi + if echo $RHKL | grep HUGEMEM + then + RHKL=$(echo $RHKL | sed 's/BIGMEM//') + fi + for K in $RHKL ; do + SwitchRHKernel $K "$RHKL" + make -C src clean + if [ $KA == "x86_64" ] ; then + CFLAGS_EXTRA="$CFLAGS_EXTRA -D__MODULE_KERNEL_x86_64=0 -D__MODULE_KERNEL_ia32e=1" + fi + make -C src INSTALL_MOD_PATH=%{buildroot} \ + MANDIR=%{_mandir} CFLAGS_EXTRA="$CFLAGS_EXTRA" install + done + else + make -C src clean + make -C src INSTALL_MOD_PATH=%{buildroot} MANDIR=%{_mandir} install + fi + fi + + %install + # Append .new to driver name to avoid conflict with kernel RPM + echo "# Going to " %{buildroot} + cd %{buildroot} + find lib -name "e1000e.*o" -exec mv {} {}.new \; \ + -fprintf %{_builddir}/%{driver_name}-%{version}/file.list "/%p.new\n" + + + %clean + rm -rf %{buildroot} + + %files -f %{_builddir}/%{driver_name}-%{version}/file.list + %defattr(-,root,root) + %{_mandir}/man7/e1000e.7.gz + %doc COPYING + %doc README + %doc file.list + %doc pci.updates + + ########################### end RPM build section + + ########################### begin RPM installation section + + %post + FL="%{_docdir}/%{name}-%{version}/file.list + %{_docdir}/%{name}/file.list" + FL=$(for d in $FL ; do if [ -e $d ]; then echo $d; break; fi; done) + + if [ -d /usr/local/lib/%{name} ]; then + rm -rf /usr/local/lib/%{name} + fi + if [ -d /usr/local/share/%{name} ]; then + rm -rf /usr/local/share/%{name} + fi + + echo "original pci.ids saved in /usr/local/share/%{name}"; + if [ "%{pcitable}" != "/dev/null" ]; then + echo "original pcitable saved in /usr/local/share/%{name}"; + fi + + #### Save old drivers (aka .o and .o.gz) in $d_usr + # k is(are) the kernel version(s) extracted with sed from the full qualified + # kernel module name(s) in file.list + echo "Original drivers saved in /usr/local/share/%{name}"; + for k in $(sed 's/\/lib\/modules\/\([0-9a-zA-Z_\.\-]*\).*/\1/' $FL) ; + do + d_drivers=/lib/modules/$k + d_usr=/usr/local/share/%{name}/$k + mkdir -p $d_usr + cd $d_drivers; find . -name %{driver_name}.*o -exec cp --parents {} $d_usr \; -exec rm -f {} \; + cd $d_drivers; find . -name %{driver_name}_*.*o -exec cp --parents {} $d_usr \; -exec rm -f {} \; + cd $d_drivers; find . -name %{driver_name}.*o.gz -exec cp --parents {} $d_usr \; -exec rm -f {} \; + cd $d_drivers; find . -name %{driver_name}_*.*o.gz -exec cp --parents {} $d_usr \; -exec rm -f {} \; + cp --parents %{pciids} /usr/local/share/%{name}/ + if [ "%{pcitable}" != "/dev/null" ]; then + cp --parents %{pcitable} /usr/local/share/%{name}/ + fi + done + + # Add driver link + for f in $(sed 's/\.new$//' $FL) ; do + ln -f $f.new $f + done + + # Check if kernel version rpm was built on IS the same as running kernel + BK_LIST=$(sed 's/\/lib\/modules\/\([0-9a-zA-Z_\.\-]*\).*/\1/' $FL) + MATCH=no + for i in $BK_LIST + do + if [ $(uname -r) == $i ] ; then + MATCH=yes + break + fi + done + if [ $MATCH == no ] ; then + echo -n "WARNING: Running kernel is $(uname -r). " + echo -n "RPM supports kernels ( " + for i in $BK_LIST + do + echo -n "$i " + done + echo ")" + fi + + LD="%{_docdir}/%{name}"; + if [ -d %{_docdir}/%{name}-%{version} ]; then + LD="%{_docdir}/%{name}-%{version}"; + fi + + #Yes, this really needs bash + bash -s %{pciids} \ + %{pcitable} \ + $LD/pci.updates \ + $LD/pci.ids.new \ + $LD/pcitable.new \ + %{name} \ + <<"END" + #! /bin/bash + # $1 = system pci.ids file to update + # $2 = system pcitable file to update + # $3 = file with new entries in pci.ids file format + # $4 = pci.ids output file + # $5 = pcitable output file + # $6 = driver name for use in pcitable file + + exec 3<$1 + exec 4<$2 + exec 5<$3 + exec 6>$4 + exec 7>$5 + driver=$6 + IFS= + + # pattern matching strings + ID="[[:xdigit:]][[:xdigit:]][[:xdigit:]][[:xdigit:]]" + VEN="${ID}*" + DEV=" ${ID}*" + SUB=" ${ID}*" + TABLE_DEV="0x${ID} 0x${ID} \"*" + TABLE_SUB="0x${ID} 0x${ID} 0x${ID} 0x${ID} \"*" + + line= + table_line= + ids_in= + table_in= + vendor= + device= + ids_device= + table_device= + subven= + ids_subven= + table_subven= + subdev= + ids_subdev= + table_subdev= + ven_str= + dev_str= + sub_str= + + # force a sub-shell to fork with a new stdin + # this is needed if the shell is reading these instructions from stdin + while true + do + # get the first line of each data file to jump start things + exec 0<&3 + read -r ids_in + if [ "$2" != "/dev/null" ];then + exec 0<&4 + read -r table_in + fi + + # outer loop reads lines from the updates file + exec 0<&5 + while read -r line + do + # vendor entry + if [[ $line == $VEN ]] + then + vendor=0x${line:0:4} + ven_str=${line#${line:0:6}} + # add entry to pci.ids + exec 0<&3 + exec 1>&6 + while [[ $ids_in != $VEN || + 0x${ids_in:0:4} < $vendor ]] + do + echo "$ids_in" + read -r ids_in + done + echo "$line" + if [[ 0x${ids_in:0:4} == $vendor ]] + then + read -r ids_in + fi + + # device entry + elif [[ $line == $DEV ]] + then + device=`echo ${line:1:4} | tr [:upper:] [:lower:]` + table_device=0x${line:1:4} + dev_str=${line#${line:0:7}} + ids_device=`echo ${ids_in:1:4} | tr [:upper:] [:lower:]` + table_line="$vendor $table_device \"$driver\" \"$ven_str|$dev_str\"" + # add entry to pci.ids + exec 0<&3 + exec 1>&6 + while [[ $ids_in != $DEV || + $ids_device < $device ]] + do + if [[ $ids_in == $VEN ]] + then + break + fi + if [[ $ids_device != ${ids_in:1:4} ]] + then + echo "${ids_in:0:1}$ids_device${ids_in#${ids_in:0:5}}" + else + echo "$ids_in" + fi + read -r ids_in + ids_device=`echo ${ids_in:1:4} | tr [:upper:] [:lower:]` + done + if [[ $device != ${line:1:4} ]] + then + echo "${line:0:1}$device${line#${line:0:5}}" + else + echo "$line" + fi + if [[ $ids_device == $device ]] + then + read -r ids_in + fi + # add entry to pcitable + if [ "$2" != "/dev/null" ];then + exec 0<&4 + exec 1>&7 + while [[ $table_in != $TABLE_DEV || + ${table_in:0:6} < $vendor || + ( ${table_in:0:6} == $vendor && + ${table_in:7:6} < $table_device ) ]] + do + echo "$table_in" + read -r table_in + done + echo "$table_line" + if [[ ${table_in:0:6} == $vendor && + ${table_in:7:6} == $table_device ]] + then + read -r table_in + fi + fi + # subsystem entry + elif [[ $line == $SUB ]] + then + subven=`echo ${line:2:4} | tr [:upper:] [:lower:]` + subdev=`echo ${line:7:4} | tr [:upper:] [:lower:]` + table_subven=0x${line:2:4} + table_subdev=0x${line:7:4} + sub_str=${line#${line:0:13}} + ids_subven=`echo ${ids_in:2:4} | tr [:upper:] [:lower:]` + ids_subdev=`echo ${ids_in:7:4} | tr [:upper:] [:lower:]` + table_line="$vendor $table_device $table_subven $table_subdev \"$driver\" \"$ven_str|$sub_str\"" + # add entry to pci.ids + exec 0<&3 + exec 1>&6 + while [[ $ids_in != $SUB || + $ids_subven < $subven || + ( $ids_subven == $subven && + $ids_subdev < $subdev ) ]] + do + if [[ $ids_in == $VEN || + $ids_in == $DEV ]] + then + break + fi + if [[ ! (${ids_in:2:4} == "1014" && + ${ids_in:7:4} == "052C") ]] + then + if [[ $ids_subven != ${ids_in:2:4} || $ids_subdev != ${ids_in:7:4} ]] + then + echo "${ids_in:0:2}$ids_subven $ids_subdev${ids_in#${ids_in:0:11}}" + else + echo "$ids_in" + fi + fi + read -r ids_in + ids_subven=`echo ${ids_in:2:4} | tr [:upper:] [:lower:]` + ids_subdev=`echo ${ids_in:7:4} | tr [:upper:] [:lower:]` + done + if [[ $subven != ${line:2:4} || $subdev != ${line:7:4} ]] + then + echo "${line:0:2}$subven $subdev${line#${line:0:11}}" + else + echo "$line" + fi + if [[ $ids_subven == $subven && + $ids_subdev == $subdev ]] + then + read -r ids_in + fi + # add entry to pcitable + if [ "$2" != "/dev/null" ];then + exec 0<&4 + exec 1>&7 + while [[ $table_in != $TABLE_SUB || + ${table_in:14:6} < $table_subven || + ( ${table_in:14:6} == $table_subven && + ${table_in:21:6} < $table_subdev ) ]] + do + if [[ $table_in == $TABLE_DEV ]] + then + break + fi + if [[ ! (${table_in:14:6} == "0x1014" && + ${table_in:21:6} == "0x052C") ]] + then + echo "$table_in" + fi + read -r table_in + done + echo "$table_line" + if [[ ${table_in:14:6} == $table_subven && + ${table_in:21:6} == $table_subdev ]] + then + read -r table_in + fi + fi + fi + + exec 0<&5 + done + + # print the remainder of the original files + exec 0<&3 + exec 1>&6 + echo "$ids_in" + while read -r ids_in + do + echo "$ids_in" + done + + if [ "$2" != "/dev/null" ];then + exec 0>&4 + exec 1>&7 + echo "$table_in" + while read -r table_in + do + echo "$table_in" + done + fi + + break + done <&5 + + exec 3<&- + exec 4<&- + exec 5<&- + exec 6>&- + exec 7>&- + + END + + mv -f $LD/pci.ids.new %{pciids} + if [ "%{pcitable}" != "/dev/null" ]; then + mv -f $LD/pcitable.new %{pcitable} + fi + + uname -r | grep BOOT || /sbin/depmod -a > /dev/null 2>&1 || true + + ########################### end RPM installation section + + ########################### begin RPM deinstallation section + %preun + # If doing RPM un-install + if [ $1 -eq 0 ] ; then + FL="%{_docdir}/%{name}-%{version}/file.list + %{_docdir}/%{name}/file.list" + FL=$(for d in $FL ; do if [ -e $d ]; then echo $d; break; fi; done) + + # Remove driver link + for f in $(sed 's/\.new$//' $FL) ; do + rm -f $f + done + + # Restore old drivers + if [ -d /usr/local/share/%{name} ]; then + cd /usr/local/share/%{name}; find . -name '%{driver_name}.*o*' -exec cp --parents {} /lib/modules/ \; + cd /usr/local/share/%{name}; find . -name '%{driver_name}_*.*o*' -exec cp --parents {} /lib/modules/ \; + rm -rf /usr/local/share/%{name} + fi + fi + + %postun + uname -r | grep BOOT || /sbin/depmod -a > /dev/null 2>&1 || true + + ########################### end RPM deinstallation section + + #### end e1000e.spec + + =closetwisty + + =head3 Create the Customization Key for the e1000e Driver, Example for x86_64 + + Go to the customization key directory for SL5.1 and create the basic + files. + + # cd /afs/psi.ch/software/linux/dist/scientific/51/kickstart/custom/ + # mkdir e1000e + # cd e1000e + # touch custom.sh + # vi custom.sh + + =opentwisty + + #!/bin/bash + # + # KS Customization for e1000e driver + # + # marc.gasser@psi.ch + # 2009-02-24 + # + # KSII scriplet rules apply + # + # This customization was added for the Intel Gigabit ethernet + # card 82567LM, which comes with the new Fujitsu Siemens computers + # Celsius W370, Esprimo p7935 e80, Esprimo e7935 e80 and Lifebook e8420, + # because the e1000e.ko version 0.2.0 coming with SL kernels <= 2.6.18-92.1.22.el5 + # does not support this kind of hardware. + # + ############################################################## + # Changelog: + # --------- + # + ############################################################## + + ARCH=$(uname -m) + DIR_E1000E=/mnt/master/linux/dist/scientific/51/psi/all + + # Install the kernel-module-e1000e containing the e1000e driver + if test "$ARCH" = "x86_64" + then + echo "Install kernel-module-e1000e for $ARCH" >> $POSTLOG 2>&1 + rpm -ivh $DIR_E1000E/kernel-module-e1000e-2.6.18-92.1.22.el5-0.4.1.7-1.x86_64.rpm || \ + echo error installing kernel-module-e1000e \ + >> $POSTLOG 2>&1 + else + echo "Install kernel-module-e1000e for $ARCH" >> $POSTLOG 2>&1 + rpm -ivh $DIR_E1000E/kernel-module-e1000e-2.6.18-92.1.22.el5-0.4.1.7-1.i386.rpm || \ + echo error installing kernel-module-e1000e \ + >> $POSTLOG 2>&1 + fi + + =closetwisty + + Copy the kernel-module-e1000e RPMS to F + and F, create the symbolic links + in the corresponding F and/or F repositories, and run C + within F and/or F. + + That's it. Now you can test the installation using the custom key + F. diff --git a/admin-guide/legacy/misc/linuxhowto-rpm-updatepsi-desktoppackageonsl5.rst b/admin-guide/legacy/misc/linuxhowto-rpm-updatepsi-desktoppackageonsl5.rst new file mode 100644 index 00000000..76eb5948 --- /dev/null +++ b/admin-guide/legacy/misc/linuxhowto-rpm-updatepsi-desktoppackageonsl5.rst @@ -0,0 +1,236 @@ +Linux How To - RPM - Update psi-desktop Package on SL5 +====================================================== + +Introduction +------------ + +Contemporary there are many PSI related cron jobs which are executed +at the same time on all linux clients. As a consequence too many AFS +requests coming from these clients are sent simultaneously to the AFS +servers causing AFS performance problems. Thus, these cron jobs should +be spread over time. In order to have time to fix things if anything +goes wrong, the respective jobs are scheduled within a certain time +window instead of using the whole time range, e.g. the hourly executed +job window ranges from 20-40 minutes of an hour and not from 0-59 +minutes. + +At the time of writing only `/usr/sbin/psi-puppet` is configured to +run within such a window, the time is set randomly in +`/etc/cron.d/psi-cronjobs` during installation of the RPM psi-desktop +to which the file belongs to, 27 in the example below:: + + # + # /etc/cron.d/psi-cronjobs + # + # PSI related cronjobs + # + # Urs Beyerle, PSI + # + + # Run puppet every hour at xx:27 + 27 * * * * root /usr/sbin/psi-puppet >/dev/null 2>&1 + + # Send info back to master daily at 10:00 + 00 10 * * * root /usr/sbin/psi-sendinfo >/dev/null 2>&1 + + # Run psi-auto-udpate daily at 00:30, 01:30, 02:30, 04:30 + 30 00 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + 30 02 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + 30 03 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + 30 04 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + + +- /usr/sbin/psi-puppet: Runs puppetd, but only if AUTO_UPDATE_CONFIG=yes +- /usr/sbin/psi-auto-update: Runs the psi-update script if AUTO_UPDATE_RPMS=yes +- /usr/sbin/psi-update: Runs the yum_update script + (Will get the script yum_update from our master. + The script yum_update will be saved as psi-yum_update. + Afterwards psi-yum_update will be executed locally.) + +Now the following jobs should be scheduled analogously.#??? + +- `/etc/cron.hourly/update_afs_users` + +- `/etc/cron.hourly/update_environment_modules` + +Maybe the time window for `/usr/sbin/psi-puppet` has to be expanded. + +- Are there GFA related things which should be scheduled in a new manner?#??? + +Procedure Description +~~~~~~~~~~~~~~~~~~~~~ + +Go to the relevant build system (e.g. tux50). Get the sources for +building the psi-desktop RPM, unpack them and apply your modifications +in the unpacked files. When finished tar and gzip again, build the new +RPM, and, eventually, test it on a test machine. + + +Procedure Step by Step +~~~~~~~~~~~~~~~~~~~~~~ + +Get The Source RPM +.................... + +Run:: + + # [gasser_m@tux50] + # cd /scratch/gasser_m/rpm_topdir/SRPMS/ + # ll /scratch/redhat/SRPMS/ + total 11M + -rw-r--r-- 1 beyerle ait 4.9M Jun 30 08:09 psi-desktop-1.3.3-16.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 4.9M Jun 30 08:11 psi-desktop-1.3.3-17.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 5.3K Jun 30 10:32 nxcleanup-0.3-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 6.0K Jul 9 10:40 nxcleanup-0.4-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 418K Jul 16 10:48 aufs-0.20080605.cvs-5.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 642K Jul 29 12:57 ntfs-3g-1.2712-4.slp5.src.rpm + + # cp /scratch/redhat/SRPMS/psi-desktop-1.3.3-17.slp5.src.rpm . + # rpm -ivh psi-desktop-1.3.3-17.slp5.src.rpm + +This will install the files +`/scratch/gasser_m/rpm_topdir/SOURCES/psi-desktop-1.3.3.tar.gz` and +`/scratch/gasser_m/rpm_topdir/SPECS/psi-desktop.spec`:: + + # cd /scratch/gasser_m/rpm_topdir/SOURCES/ + # tar xfz psi-desktop-1.3.3.tar.gz + +Apply Your Modifications +........................ + +Edit `/scratch/gasser_m/rpm_topdir/SPECS/psi-desktop.spec`:: + + Modified Parts in "psi-desktop.spec" + ------------------------------------ + Note: Some lines are cut at the end. + + NEW VERSION | OLD VERSION + --------------------------------------------------------------------------------------------------------------------- + ... + Release: 18%{?dist} | Release: 17%{?dist} + ... + Packager: Marc Gasser | Packager: Urs Beyerle + ... + #### begin psi-cronjobs ############################ | # randomly runs puppet in psi-cronjobs + # | # create a random number between 0-9 + # Randomly run commands in "/etc/cron.d/psi-cronjobs" | random=${RANDOM:1:1} + # | [ ! $random ] && random=0 + # /usr/sbin/psi-puppet: hourly at random1 | sed -i "s/random/$random/" /etc/cron.d/psi-cronjobs + random1=$[ ( $RANDOM % 20 ) + 21 ] # create a random n| + [ ! $random1 ] && random1=33 | + sed -i "s/random1/$random1/g" /etc/cron.d/psi-cronjobs | + | + # /usr/sbin/psi-sendinfo: daily at 10:1random2 | + # /usr/sbin/update_environment_modules: daily at 06:0random| + # /usr/sbin/update_afs_users: hourly at XX:1random2 | + random2=$[ ( $RANDOM % 10 ) ] # create a random number be| + [ ! $random2 ] && random2=3 | + sed -i "s/random2/$random2/g" /etc/cron.d/psi-cronjobs | + | + #### end psi-cronjobs ############################ | + ... + --------------------------------------------------------------------------------------------------------------------- + + +Edit `/etc/cron.d/psi-cronjobs`. The modified `psi-cronjobs` which +will be packed into the new `psi-desktop` RPM:: + + # cd /scratch/gasser_m/rpm_topdir/SOURCES/psi-desktop-1.3.3/slp5/etc/cron.d + # vi psi-cronjobs + + # + # /etc/cron.d/psi-cronjobs + # + # PSI related cronjobs + # + # Marc Gasser, PSI + # + # Note: The time settings for these cron jobs are + # set in "psi-desktop.spec". They are + # randomized within a specific time window. + # The randomization takes place when the RPM is + # installed, thus it is client specific. + + + # Run psi-puppet every hour at XX:random1 + random1 * * * * root /usr/sbin/psi-puppet >/dev/null 2>&1 + + # Send info back to master daily at 10:1random2 + 1random2 10 * * * root /usr/sbin/psi-sendinfo >/dev/null 2>&1 + + # Run psi-auto-udpate daily at 00:4random2, 01:4random2, 02:4random2, 04:4random2 + 4random2 00 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + 4random2 02 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + 4random2 03 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + 4random2 04 * * * root /usr/sbin/psi-auto-update >> /var/log/update/psi-update.log 2>&1 + + # Run update_environment_modules daily at 06:0random2, 13:0random2, 18:0random2 + 0random2 06 * * * root /usr/sbin/update_environment_modules >/dev/null 2>&1 + 0random2 13 * * * root /usr/sbin/update_environment_modules >/dev/null 2>&1 + 0random2 18 * * * root /usr/sbin/update_environment_modules >/dev/null 2>&1 + + # Run update_afs_users every hour at XX:1random2 + 1random2 * * * * root /usr/sbin/update_afs_users >/dev/null 2>&1 + + +Move commands which are controlled by `/etc/cron.d/psi-cronjobs` to +`/usr/sbin/` if not done yet:: + + # cd /scratch/gasser_m/rpm_topdir/SOURCES/psi-desktop-1.3.3/slp5/ + # mv etc/cron.d/update_environment_modules usr/sbin/ + # mv etc/cron.d/update_afs_users usr/sbin/ + +Cronjob Schedule in `psi-cronjobs` +.................................. + +Applying this `psi-desktop.spec` to the file `psi-cronjobs` will +randomly distribute the respective cronjobs whithin the time windows +given below. The randomization takes place when the RPM is installed +or updated on the client. + +- `/usr/sbin/psi-puppet`: hourly from HH:21 to HH:40. + +- `/usr/sbin/psi-sendinfo`: daily from 10:10 to 10:19. + +- `/usr/sbin/update_environment_modules`: daily from 06:00 to 06:09, + from 13:00 to 13:09 and from 18:00 to 18:09. + +- `/usr/sbin/update_afs_users`: hourly from HH:10 to HH:19. + + +Build the new `psi-desktop` RPM +............................... + +Build both, the new RPM and the new SRPM applying the spec file:: + + # cd /scratch/gasser_m/rpm_topdir/SOURCES/ + # tar cfz psi-desktop-1.3.3.tar.gz psi-desktop-1.3.3 + # rm -rf psi-desktop-1.3.3/ + # cd /scratch/gasser_m/rpm_topdir/SPECS/ + # rpmbuild -ba psi-desktop.spec + +Test the New `psi-desktop` RPM +.............................. + +The file +`tux50:/scratch/gasser_m/rpm_topdir/RPMS/noarch/psi-desktop-1.3.3-18.slp5.noarch.rpm` +was copied to `pc7377:/tmp/` and updated using yum:: + + # [root@pc7377 etc] + # yum update /tmp/psi-desktop-1.3.3-18.slp5.noarch.rpm + + +Add the New `psi-desktop` RPM to Psi-All Repository +................................................... + +Copy the new RPM to the respective SL5 repository. Update the +`repodata` and the symbolic links in `.../RPMSall/...` if necessary:: + + # [gasser_m@tux50 ~] + # cd /scratch/gasser_m/rpm_topdir/RPMS/noarch/ + # cp psi-desktop-1.3.3-18.slp5.noarch.rpm /afs/psi.ch/software/linux/dist/scientific/51/psi/all/ + + # cd /afs/psi.ch/software/linux/dist/scientific/51/psi/all/ + # createrepo . + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts + # make rpms_all diff --git a/admin-guide/legacy/misc/linuxhowto-sl5-nvidiadriverinstallationupdate.rst b/admin-guide/legacy/misc/linuxhowto-sl5-nvidiadriverinstallationupdate.rst new file mode 100644 index 00000000..764dd56f --- /dev/null +++ b/admin-guide/legacy/misc/linuxhowto-sl5-nvidiadriverinstallationupdate.rst @@ -0,0 +1,452 @@ +Linux How To - SL5 - Nvidia Driver Installation/Update On SL51 i386 +=================================================================== + +References +---------- + +- https://wiki.intranet.psi.ch/AIT/Linux/HowToDKMS?skin=clean.nat%2cpsiskin%2cpattern #Update_nvidia_x11_drv_driver_to + +- [[DynamicKernelModuleSupportBasics][Dynamic Kernel Module Support (DKMS) Basics]] + + +Requirements +~~~~~~~~~~~~ + +DKMS (Dynamic Kernel Module Support) framework has to be installed +before the nvidia RPM installation, because the RPM scripts use it for +proper setup:: + + # yum install dkms.noarch + + +Procedure +~~~~~~~~~ + +Check what graphic card is in your computer and what driver is +installed:: + + # lspci + ... + 01:00.0 VGA compatible controller: nVidia Corporation G72 [GeForce 7300 LE] (rev a1) + + # less /etc/X11/xorg.conf + (See the output below at "before nvidia installation".) + + # rpm -qa | grep nvid + (nothing found) + +Before beginning with the installation of the new graphics driver, +make a backup of your current `xorg.conf`:: + + # cd /etc/X11/ + # cp xorg.conf xorg.conf_bak + +Check whether some nvidia driver is available:: + + # [root@pc7377 X11]# yum list | grep nvidia + nvidia-x11-drv.i386 100.14.19-3.9.slp5 sl51psi + + # [root@pc7377 X11]# yum install nvidia-x11-drv.i386 + + + ### begin output + Loading "kernel-module" plugin + Setting up Install Process + Setting up repositories + Reading repository metadata in from local files + Parsing package install arguments + Resolving Dependencies + --> Populating transaction set with selected packages. Please wait. + ---> Downloading header for nvidia-x11-drv to pack into transaction set. + nvidia-x11-drv-100.14.19- 100% |=========================| 24 kB 00:00 + ---> Package nvidia-x11-drv.i386 0:100.14.19-3.9.slp5 set to be updated + --> Running transaction check + --> Processing Dependency: dkms for package: nvidia-x11-drv + --> Restarting Dependency Resolution with new changes. + --> Populating transaction set with selected packages. Please wait. + ---> Downloading header for dkms to pack into transaction set. + dkms-2.0.17.4-1.9.slp5.no 100% |=========================| 36 kB 00:00 + ---> Package dkms.noarch 0:2.0.17.4-1.9.slp5 set to be updated + --> Running transaction check + Beginning Kernel Module Plugin + Finished Kernel Module Plugin + + Dependencies Resolved + + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Installing: + nvidia-x11-drv i386 100.14.19-3.9.slp5 sl51psi 7.1 M + Installing for dependencies: + dkms noarch 2.0.17.4-1.9.slp5 sl51psi 89 k + + Transaction Summary + ============================================================================= + Install 2 Package(s) + Update 0 Package(s) + Remove 0 Package(s) + + Total download size: 7.2 M + Is this ok [y/N]: y + Downloading Packages: + (1/2): nvidia-x11-drv-100 100% |=========================| 7.1 MB 00:00 + (2/2): dkms-2.0.17.4-1.9. 100% |=========================| 89 kB 00:00 + Running Transaction Test + Finished Transaction Test + Transaction Test Succeeded + Running Transaction + Installing: dkms ######################### [1/2] + Installing: nvidia-x11-drv ######################### [2/2] + + Installed: nvidia-x11-drv.i386 0:100.14.19-3.9.slp5 + Dependency Installed: dkms.noarch 0:2.0.17.4-1.9.slp5 + Complete! + [root@pc7377 X11]# dkms status -m nvidia + nvidia, 100.14.19-3.9.slp5, 2.6.18-92.1.10.el5, i686: installed + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.4.el5, i686: installed-weak from 2.6.18-92.1.10.el5 + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.21.el5, i686: installed-weak from 2.6.18-92.1.10.el5 + [root@pc7377 X11]# rpm -q --scripts nvidia-x11-drv-100 + package nvidia-x11-drv-100 is not installed + [root@pc7377 X11]# rpm -q --scripts nvidia-x11-drv + postinstall scriptlet (using /bin/sh): + /sbin/ldconfig + # Make sure we have a Files section in xorg.conf, otherwise create an empty one + XORGCONF=/etc/X11/xorg.conf + [ -w ${XORGCONF} ] && ! grep -q 'Section "Files"' ${XORGCONF} && \ + echo -e 'Section "Files"\nEndSection' >> ${XORGCONF} + # Enable the proprietary driver + /usr/sbin/nvidia-config-display enable || : + # Add to DKMS registry + dkms add -m nvidia -v 100.14.19-3.9.slp5 -q || : + # Rebuild and make available for the currenty running kernel + dkms build -m nvidia -v 100.14.19-3.9.slp5 -q || : + dkms install -m nvidia -v 100.14.19-3.9.slp5 -q --force || : + /sbin/MAKEDEV nvidia + preuninstall scriptlet (using /bin/sh): + # Remove all versions from DKMS registry + dkms remove -m nvidia -v 100.14.19-3.9.slp5 -q --all || : + # Last removal, disable the proprietary driver + if [ $1 -eq 0 ]; then + /usr/sbin/nvidia-config-display disable || : + fi + postuninstall program: /sbin/ldconfig + ### end output + +Check the status of the nvidia kernel module. (From the dkms manpage: +`dkms status` returns the current status of modules, versions and +kernels within the tree as well as whether they have been added, built +or installed.):: + + # dkms status -m nvidia + nvidia, 100.14.19-3.9.slp5, 2.6.18-92.1.10.el5, i686: installed + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.4.el5, i686: installed-weak from 2.6.18-92.1.10.el5 + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.21.el5, i686: installed-weak from 2.6.18-92.1.10.el5 + +List the package specific scriptlet(s) that are used as part of the +installation and uninstallation processes:: + + # rpm -q --scripts nvidia-x11-drv + + ### begin output + postinstall scriptlet (using /bin/sh): + /sbin/ldconfig + # Make sure we have a Files section in xorg.conf, otherwise create an empty one + XORGCONF=/etc/X11/xorg.conf + [ -w ${XORGCONF} ] && ! grep -q 'Section "Files"' ${XORGCONF} && \ + echo -e 'Section "Files"\nEndSection' >> ${XORGCONF} + # Enable the proprietary driver + /usr/sbin/nvidia-config-display enable || : + # Add to DKMS registry + dkms add -m nvidia -v 100.14.19-3.9.slp5 -q || : + # Rebuild and make available for the currenty running kernel + dkms build -m nvidia -v 100.14.19-3.9.slp5 -q || : + dkms install -m nvidia -v 100.14.19-3.9.slp5 -q --force || : + /sbin/MAKEDEV nvidia + preuninstall scriptlet (using /bin/sh): + # Remove all versions from DKMS registry + dkms remove -m nvidia -v 100.14.19-3.9.slp5 -q --all || : + # Last removal, disable the proprietary driver + if [ $1 -eq 0 ]; then + /usr/sbin/nvidia-config-display disable || : + fi + postuninstall program: /sbin/ldconfig + ### end output + + +Check whether your xorg.conf was modified to use the nvidia driver:: + + # less /etc/X11/xorg.conf + + ### begin output + (after nvidia installation) # (before nvidia installation) + # Xorg configuration created by pyxf86config # # Xorg configuration created by pyxf86config + # + Section "ServerLayout" # Section "ServerLayout" + Identifier "Default Layout" # Identifier "Default Layout" + Screen 0 "Screen0" 0 0 # Screen 0 "Screen0" 0 0 + InputDevice "Keyboard0" "CoreKeyboard" # InputDevice "Keyboard0" "CoreKeyboard" + EndSection # EndSection + # + Section "Files" # + ModulePath "/usr/lib/xorg/modules/extensions/nvidia" # + ModulePath "/usr/lib/xorg/modules" # + EndSection # + # + Section "InputDevice" # Section "InputDevice" + Identifier "Keyboard0" # Identifier "Keyboard0" + Driver "kbd" # Driver "kbd" + Option "XkbModel" "pc105" # Option "XkbModel" "pc105" + Option "XkbLayout" "ch" # Option "XkbLayout" "ch" + Option "XkbVariant" "de_nodeadkeys" # Option "XkbVariant" "de_nodeadkeys" + EndSection # EndSection + # + Section "Device" # Section "Device" + Identifier "Videocard0" # Identifier "Videocard0" + Driver "nvidia" # Driver "nv" + EndSection # EndSection + # + Section "Screen" # Section "Screen" + Identifier "Screen0" # Identifier "Screen0" + Device "Videocard0" # Device "Videocard0" + DefaultDepth 24 # DefaultDepth 24 + SubSection "Display" # SubSection "Display" + Viewport 0 0 # Viewport 0 0 + Depth 24 # Depth 24 + EndSubSection # EndSubSection + EndSection # EndSection + ### end output # + + +Test the module with glxgears for instance:: + + [root@pc7377 ~]# glxgears + + 11424 frames in 5.0 seconds = 2284.662 FPS + 11291 frames in 5.0 seconds = 2258.003 FPS + 11244 frames in 5.0 seconds = 2248.682 FPS + 11290 frames in 5.0 seconds = 2257.974 FPS + 12626 frames in 5.0 seconds = 2525.121 FPS + 3439 frames in 5.0 seconds = 687.363 FPS + 964 frames in 5.0 seconds = 192.629 FPS + 964 frames in 5.0 seconds = 192.620 FPS + 1395 frames in 5.0 seconds = 278.978 FPS + 12080 frames in 5.0 seconds = 2415.854 FPS + 11252 frames in 5.0 seconds = 2250.348 FPS + + +Problem With Automatic Nvidia Driver Update On SL51 i386 +-------------------------------------------------------- + +Problem Description +~~~~~~~~~~~~~~~~~~~ + +On some systems the automatic nvidia driver update by dkms fails. +Somehow when the new RPM `nvidia-x11-drv-169.12-4.9.slp5` is installed +by yum or rpm, the old nvidia version `100.14.19-3.9.slp5` remains in +dkms status `added`, i.e. the respective directory remains in the dkms +tree, while the original driver sources are removed from `/usr/src/`, +i.e. the RPM `nvidia-x11-drv-100.14.19-3.9.slp5` was removed. + +During reboot the service `dkms_autoinstaller` (see `chkconfig +--list`) obviously tries to build the old `100.14.19-3.9.slp5` as well +because it tries to get the file +`/var/lib/dkms/nvidia/100.14.19-3.9.slp5/source/dkms.conf`. This, +however, fails because the `.../scource` is a symbolic link pointing +to the source directory that was removed during the nvidia RPM update +as mentioned before:: + + "source -> /usr/src/nvidia-100.14.19-3.9.slp5" + +Though, this basically would not be a problem if dkms was not confused +by the occurences of several nvidia versions in its tree under +`/var/lib/dkms/nvidia/`. + +The main questions are: + +- Why does the update procedure only partially clean the installation + environment (under `/usr/src/` it is clean, under + `/var/lib/dkms/nvidia/` it is not)? + +- Why does dkms not properly recognize the new nvidia version only but + also tries to build modules out of the sources of the older version? + + +Solution +~~~~~~~~ + +The problem appears if the nvidia driver RPM is installed or updated +before the dkms framework is ready on the system, because the RPM +scripts invoke a variety of `dkms` commands to install the new driver +into the dkms tree and to remove the old driver version from it. Thus, +one has to install the dkms RPM first, before doing any driver +installation or updates. + +Manual Update Using DKMS +~~~~~~~~~~~~~~~~~~~~~~~~ + +Perform the following steps:: + + [root@pc7377 ~]# dkms status -m nvidia + nvidia, 100.14.19-3.9.slp5, 2.6.18-92.1.10.el5, i686: installed + nvidia, 100.14.19-3.9.slp5, 2.6.18-92.1.13.el5, i686: installed + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.4.el5, i686: installed-weak from 2.6.18-92.1.10.el5 + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.4.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.21.el5, i686: installed-weak from 2.6.18-92.1.10.el5 + nvidia, 100.14.19-3.9.slp5, 2.6.18-53.1.21.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + nvidia, 100.14.19-3.9.slp5, 2.6.18-92.1.10.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + + [root@pc7377 ~]# uname -a + Linux pc7377 2.6.18-92.1.13.el5 #1 SMP Wed Sep 24 16:44:34 EDT 2008 i686 i686 i386 GNU/Linux + + [root@pc7377 ~]# locate nvidia.ko + /lib/modules/2.6.18-53.1.21.el5/weak-updates/lib/modules/2.6.18-92.1.10.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-53.1.21.el5/weak-updates/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-53.1.4.el5/weak-updates/lib/modules/2.6.18-92.1.10.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-53.1.4.el5/weak-updates/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-92.1.10.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-92.1.10.el5/weak-updates/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /var/lib/dkms/nvidia/100.14.19-3.9.slp5/2.6.18-92.1.10.el5/i686/module/nvidia.ko + /var/lib/dkms/nvidia/100.14.19-3.9.slp5/2.6.18-92.1.13.el5/i686/module/nvidia.ko + + [root@pc7377 ~]# rpm -q nvidia-x11-drv + nvidia-x11-drv-100.14.19-3.9.slp5 + + [root@pc7377 ~]# cp -i /etc/X11/xorg.conf /etc/X11/xorg.conf_orig + + [root@pc7377 ~]# yum --enablerepo=psi-beta update nvidia-x11-drv + ... + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Updating: + nvidia-x11-drv i386 169.12-4.9.slp5 psi-beta 9.7 M + + Transaction Summary + ============================================================================= + Install 0 Package(s) + Update 1 Package(s) + Remove 0 Package(s) + + Total download size: 9.7 M + Is this ok [y/N]: y + Downloading Packages: + (1/1): nvidia-x11-drv-169 100% |=========================| 9.7 MB 00:00 + Running Transaction Test + Finished Transaction Test + Transaction Test Succeeded + Running Transaction + Updating : nvidia-x11-drv ######################### [1/2] + + Cleanup : nvidia-x11-drv ######################### [2/2] + + Updated: nvidia-x11-drv.i386 0:169.12-4.9.slp5 + + +- Note + + `yum update` takes some time because it invokes dkms, which builds + the required module(s) on the fly and does the cleaning up, see + `nvidia.spec` or the output of `rpm -q --scripts RPM`:: + + + [root@pc7377 nvidia]# rpm -q --scripts nvidia-x11-drv-169.12-4.9.slp5 + postinstall scriptlet (using /bin/sh): + /sbin/ldconfig + # Make sure we have a Files section in xorg.conf, otherwise create an empty one + XORGCONF=/etc/X11/xorg.conf + [ -w ${XORGCONF} ] && ! grep -q 'Section "Files"' ${XORGCONF} && \ + echo -e 'Section "Files"\nEndSection' >> ${XORGCONF} + # Enable the proprietary driver + /usr/sbin/nvidia-config-display enable || : + # Add to DKMS registry + dkms add -m nvidia -v 169.12-4.9.slp5 -q || : + # Rebuild and make available for the currenty running kernel + dkms build -m nvidia -v 169.12-4.9.slp5 -q || : + dkms install -m nvidia -v 169.12-4.9.slp5 -q --force || : + /sbin/MAKEDEV nvidia + preuninstall scriptlet (using /bin/sh): + # Remove all versions from DKMS registry + dkms remove -m nvidia -v 169.12-4.9.slp5 -q --all || : + # Last removal, disable the proprietary driver + if [ $1 -eq 0 ]; then + /usr/sbin/nvidia-config-display disable || : + fi + postuninstall program: /sbin/ldconfig + + +Snapshot of output of `ps auxwf` during `yum update`:: + + ... + \_ /bin/bash + root 16677 0.0 0.0 5968 1668 pts/1 S 17:25 0:00 | \_ su - + root 16681 0.0 0.0 4804 1440 pts/1 S 17:25 0:00 | \_ -bash + root 17409 1.6 2.1 55980 44440 pts/1 S+ 17:43 0:04 | \_ /usr/bin/python /usr/bin/yum --enablerepo=psi-beta + root 17413 0.0 0.0 4452 1028 pts/1 S+ 17:44 0:00 | \_ /bin/sh /var/tmp/rpm-tmp.62532 2 + root 18088 0.0 0.0 5112 1764 pts/1 S+ 17:45 0:00 | \_ /bin/bash /usr/sbin/dkms install -m nvidia + root 18188 0.0 0.0 4456 1200 pts/1 S+ 17:45 0:00 | \_ /bin/bash /sbin/weak-modules --add-modu + root 19238 0.0 0.0 4460 692 pts/1 S+ 17:47 0:00 | \_ /bin/bash /sbin/weak-modules --add- + root 19243 5.5 0.0 2004 452 pts/1 D+ 17:47 0:00 | \_ zcat /boot/initrd-2.6.18-53.1.4 + root 19244 2.5 0.0 1816 496 pts/1 S+ 17:47 0:00 | \_ cpio -i + ... + + +When the new nvidia RPM was installed the old stuff was not cleaned up +properly, the old module sources remained in the dkms tree under +`/var/lib/dkms/nvidia/` and has to be removed manually:: + + [root@pc7377 etc]# dkms status -m nvidia + nvidia, 100.14.19-3.9.slp5: added + nvidia, 169.12-4.9.slp5, 2.6.18-92.1.13.el5, i686: installed + nvidia, 169.12-4.9.slp5, 2.6.18-53.1.4.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + nvidia, 169.12-4.9.slp5, 2.6.18-53.1.21.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + nvidia, 169.12-4.9.slp5, 2.6.18-92.1.10.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + + # rm -rf /var/lib/dkms/nvidia/100.14.19-3.9.slp5/ + # dkms status -m nvidia + nvidia, 169.12-4.9.slp5, 2.6.18-92.1.13.el5, i686: installed + nvidia, 169.12-4.9.slp5, 2.6.18-53.1.4.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + nvidia, 169.12-4.9.slp5, 2.6.18-53.1.21.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + nvidia, 169.12-4.9.slp5, 2.6.18-92.1.10.el5, i686: installed-weak from 2.6.18-92.1.13.el5 + +The `.../weak-updates/...` nvidia modules below are symbolic links to +`/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko`, +which is identical with +`/var/lib/dkms/nvidia/169.12-4.9.slp5/2.6.18-92.1.13.el5/i686/module/nvidia.ko`:: + + [root@pc7377 etc]# updatedb + [root@pc7377 etc]# locate nvidia.ko + /lib/modules/2.6.18-53.1.21.el5/weak-updates/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-53.1.4.el5/weak-updates/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-92.1.10.el5/weak-updates/lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /lib/modules/2.6.18-92.1.13.el5/kernel/drivers/video/nvidia/nvidia.ko + /var/lib/dkms/nvidia/169.12-4.9.slp5/2.6.18-92.1.13.el5/i686/module/nvidia.ko + + +Nvidia related lines in `/var/log/messages`:: + + ... + Oct 23 17:48:12 pc7377 Updated: nvidia-x11-drv.i386 169.12-4.9.slp5 + ... + Oct 24 11:16:04 pc7377 kernel: NVRM: API mismatch: the client has the version 169.12, but + Oct 24 11:16:04 pc7377 kernel: NVRM: this kernel module has the version 100.14.19. Please + Oct 24 11:16:04 pc7377 kernel: NVRM: make sure that this kernel module and all NVIDIA driver + Oct 24 11:16:04 pc7377 kernel: NVRM: components have the same version. + Oct 24 11:16:05 pc7377 gdm[6706]: gdm_slave_xioerror_handler: Fatal X error - Restarting :0 + Oct 24 11:16:09 pc7377 kernel: NVRM: API mismatch: the client has the version 169.12, but + Oct 24 11:16:09 pc7377 kernel: NVRM: this kernel module has the version 100.14.19. Please + Oct 24 11:16:09 pc7377 kernel: NVRM: make sure that this kernel module and all NVIDIA driver + Oct 24 11:16:09 pc7377 kernel: NVRM: components have the same version. + Oct 24 11:16:10 pc7377 gdm[3734]: gdm_slave_xioerror_handler: Fatal X error - Restarting :0 + Oct 24 11:16:13 pc7377 kernel: NVRM: API mismatch: the client has the version 169.12, but + Oct 24 11:16:13 pc7377 kernel: NVRM: this kernel module has the version 100.14.19. Please + Oct 24 11:16:13 pc7377 kernel: NVRM: make sure that this kernel module and all NVIDIA driver + Oct 24 11:16:13 pc7377 kernel: NVRM: components have the same version. + Oct 24 11:16:14 pc7377 gdm[3752]: gdm_slave_xioerror_handler: Fatal X error - Restarting :0 + Oct 24 11:16:14 pc7377 gdm[6489]: deal_with_x_crashes: Running the XKeepsCrashing script + ... + Oct 24 11:27:45 pc7377 kernel: nvidia: module license 'NVIDIA' taints kernel. + Oct 24 11:27:45 pc7377 kernel: ACPI: PCI Interrupt 0000:01:00.0[A] -> GSI 16 (level, low) -> IRQ 169 + Oct 24 11:27:45 pc7377 kernel: NVRM: loading NVIDIA UNIX x86 Kernel Module 169.12 Thu Feb 14 17:53:07 PST 2008 + ... diff --git a/admin-guide/legacy/misc/linuxhowtolookupforpcidevicesandcorrespondingmodulesinsl5.rst b/admin-guide/legacy/misc/linuxhowtolookupforpcidevicesandcorrespondingmodulesinsl5.rst new file mode 100644 index 00000000..46f4e7dd --- /dev/null +++ b/admin-guide/legacy/misc/linuxhowtolookupforpcidevicesandcorrespondingmodulesinsl5.rst @@ -0,0 +1,131 @@ +How To Look Up For PCI Devices And Corresponding Modules in SL5 +=============================================================== + +Weblinks +-------- + +- Intel Driver Download Center: http://downloadcenter.intel.com/ + +- Intel Support Site: http://support.intel.com/support/index.htm + +- Intel Network Connectivity: http://support.intel.com/support/network/sb/cs-008441.htm + + +Procedure Description +--------------------- + +List your PCI devices, look up for the vendor and hardware ID numbers +and search the corresponding entry in the table which maps hardware +IDs to module names. + + +This might be helpful if one has a new hardware device such as a new +network card, which is not recognized by the system because of a +missing entry in the file +`/lib/modules//modules.pcimap`, which maps devices to +modules. Assumption: the required driver (module) is present. + + +Step by Step Procedure: Example For a Working Network Card +---------------------------------------------------------- + +List your PCI devices using `lscpi`:: + + # lspci + ... + 00:19.0 Ethernet controller: Intel Corporation 82566DM-2 Gigabit Network Connection (rev 02) + ... + +Listing with `lspci -n` will show identification numbers instead of names:: + + # lspci -n + ... + 00:19.0 0200: 8086:10bd (rev 02) + ... + +- a) + + `19.0 PCI device number` + +- b) + + `0200 Hardware Type "Ethernet controller"` + +- c) + + `8086 Vendor ID "Intel Corporation"` + +- d) + + `10bd Hardware ID "82566DM-2 Gigabit Network Connection"` + + +For a very verbose output use `lspci -vv`:: + + # lspci -vv | grep 00:19 -A 15 + 00:19.0 Ethernet controller: Intel Corporation 82566DM-2 Gigabit Network Connection (rev 02) + Subsystem: Fujitsu Siemens Computer GmbH Unknown device 10fd + Control: I/O+ Mem+ BusMaster+ SpecCycle- MemWINV- VGASnoop- ParErr- Stepping- SERR+ FastB2B- + Status: Cap+ 66MHz- UDF- FastB2B- ParErr- DEVSEL=fast >TAbort- SERR- /proc/sys/net/ipv4/ip_forward + + # Director is not gw for realservers: leave icmp redirects on + echo 'setting icmp redirects (1 on, 0 off) ' + echo "1" >/proc/sys/net/ipv4/conf/all/send_redirects + cat /proc/sys/net/ipv4/conf/all/send_redirects + echo "1" >/proc/sys/net/ipv4/conf/default/send_redirects + cat /proc/sys/net/ipv4/conf/default/send_redirects + echo "1" >/proc/sys/net/ipv4/conf/eth0/send_redirects + cat /proc/sys/net/ipv4/conf/eth0/send_redirects + + # Add ethernet device and routing for VIP $VIP1 + /sbin/ifconfig eth0:1 $VIP1 broadcast $VIP1 netmask 255.255.255.255 + /sbin/route add -host $VIP1 dev eth0:1 + # Listing ifconfig info for VIP $VIP1 + /sbin/ifconfig eth0:1 + + # Check VIP $VIP1 is reachable from self (director) + /bin/ping -c 1 $VIP1 + # Listing routing info for VIP $VIP1 + /bin/netstat -rn + + ### + ### Setup_ipvsadm_table + ### + + # Clear ipvsadm table + /sbin/ipvsadm -C + + # Installing LVS services with ipvsadm + # Add ssh to VIP with round robin scheduling + /sbin/ipvsadm -A -t ${VIP1}:ssh -s rr + + # Forward ssh to realserver using direct routing with weight 1 + /sbin/ipvsadm -a -t ${VIP1}:ssh -r $RIP1 -g -w 1 + # Check realserver reachable from director + ping -c 1 $RIP1 + + # Forward ssh to realserver using direct routing with weight 1 + /sbin/ipvsadm -a -t ${VIP1}:ssh -r $RIP2 -g -w 1 + # Check realserver reachable from director + ping -c 1 $RIP2 + + # Set tcp timeout to 72 hours while leaving + # tcpfin and udp timeouts unchanged. + /sbin/ipvsadm --set 259200 0 0 + + # List timeout values + /sbin/ipvsadm -L --timeout + + # Displaying ipvsadm settings + /sbin/ipvsadm + + # Not installing a default gw for LVS_TYPE vs-dr + + ### + ### Delete an LVS entry + ### + # + # Example: remove/delete ssh forwarding to RIP2 + # + # /sbin/ipvsadm -d -t ${VIP1}:ssh -r RIP2 + # + # + + #---------------mini-rc.lvs_dr-director------------------------ + + +Realserver Configuration +........................ + +The realserver shall send responses not to the VIP of the load +balancer, rather to the client directly. This requires the iptables +rule below. + +Settings of realserver 2 for instance: + +`/etc/sysconfig/network-scripts/ifcfg-eth0`:: + + DEVICE=eth0 + BOOTPROTO=none + HWADDR=00:06:5B:8C:3C:8E + ONBOOT=yes + TYPE=Ethernet + DHCP_HOSTNAME=llc6 + PEERDNS=yes + IPADDR=129.129.190.176 + NETMASK=255.255.255.0 + GATEWAY=129.129.190.1 + USERCTL=no + IPV6INIT=no + + +`/etc/sysconfig/network`:: + + NETWORKING=yes + HOSTNAME=llc6 + + +`/etc/sysconfig/lvs`:: + + # LVS configuration file for LLC and LLCX + VIP=129.129.190.54 + + +`/etc/init.d/lvs`:: + + #! /bin/sh + # + # chkconfig: 345 90 10 + # description: Startscript to initialize this machine as an lvs real server. + + # Get network configuration + . /etc/sysconfig/network + # Get functions + . /etc/rc.d/init.d/functions + # Get VIP from the LVS configuration file + . /etc/sysconfig/lvs + + # Check that networking is up + if [ ${NETWORKING} = "no" ] ; then + exit 0 + fi + + RETVAL=0 + + # See how we were called. + case "$1" in + start) + # Add rule + echo "Starting load balancing mechanism with NAT iptables " + /sbin/iptables -t nat -A PREROUTING -d $VIP -j REDIRECT + ;; + stop) + # Delete rule + echo "Stopping load balancing mechanism with NAT iptables " + /sbin/iptables -t nat -D PREROUTING -d $VIP -j REDIRECT + ;; + *) + echo "Usage: $0 {start|stop}" + exit 1 + ;; + esac + + exit $RETVAL + + +Update Procedure +---------------- + +Director Update +~~~~~~~~~~~~~~~ + +Login to llclb1 as root and run yum update:: + + # yum clean all + # yum update + +Then reboot the director:: + + # reboot + +After rebooting no lvs rules are set by default:: + + [root@llclb1 ~]# ipvsadm -L + IP Virtual Server version 1.2.1 (size=4096) + Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn + +As soon as the realservers are updated and rebooted, too (see next +section), run the lvs setup script to initialize the lvs rules for the +ssh loadbalancing:: + + # sh /etc/setup-LVS-DR-director.conf + + + 0 + setting icmp redirects (1 on, 0 off) + 1 + 1 + 1 + SIOCADDRT: File exists + eth0:1 Link encap:Ethernet HWaddr 00:14:5E:6B:13:3E + inet addr:129.129.190.54 Bcast:129.129.190.54 Mask:255.255.255.255 + UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 + Interrupt:169 Memory:d8300000-d8310000 + + PING 129.129.190.54 (129.129.190.54) 56(84) bytes of data. + 64 bytes from 129.129.190.54: icmp_seq=1 ttl=64 time=0.053 ms + + --- 129.129.190.54 ping statistics --- + 1 packets transmitted, 1 received, 0% packet loss, time 0ms + rtt min/avg/max/mdev = 0.053/0.053/0.053/0.000 ms + Kernel IP routing table + Destination Gateway Genmask Flags MSS Window irtt Iface + 129.129.190.54 0.0.0.0 255.255.255.255 UH 0 0 0 eth0 + 129.129.190.0 0.0.0.0 255.255.255.0 U 0 0 0 eth0 + 169.254.0.0 0.0.0.0 255.255.0.0 U 0 0 0 eth0 + 0.0.0.0 129.129.190.1 0.0.0.0 UG 0 0 0 eth0 + PING 129.129.190.175 (129.129.190.175) 56(84) bytes of data. + 64 bytes from 129.129.190.175: icmp_seq=1 ttl=64 time=2.13 ms + + --- 129.129.190.175 ping statistics --- + 1 packets transmitted, 1 received, 0% packet loss, time 0ms + rtt min/avg/max/mdev = 2.139/2.139/2.139/0.000 ms + PING 129.129.190.176 (129.129.190.176) 56(84) bytes of data. + 64 bytes from 129.129.190.176: icmp_seq=1 ttl=64 time=0.172 ms + + --- 129.129.190.176 ping statistics --- + 1 packets transmitted, 1 received, 0% packet loss, time 0ms + rtt min/avg/max/mdev = 0.172/0.172/0.172/0.000 ms + Timeout (tcp tcpfin udp): 259200 120 300 + IP Virtual Server version 1.2.1 (size=4096) + Prot LocalAddress:Port Scheduler Flags + -> RemoteAddress:Port Forward Weight ActiveConn InActConn + TCP llc.psi.ch:ssh rr + -> llc6.psi.ch:ssh Route 1 1 1 + -> llc5.psi.ch:ssh Route 1 0 0 + + +Realserver Update +~~~~~~~~~~~~~~~~~ + +The realservers should be updated automatically as they are standard +SL desktop hosts. Login as root to the corresponding realserver, +e.g. llc5, and verify that the update was performed correctly, if not +fix it first. + +Then reboot the realserver. The iptables rule for the direct routing +are initialized automatically by the init script /etc/init.d/lvs:: + + # reboot + +Eventually, test the ssh connection from any client to llc:: + + # [anyuser@anyhost] ssh llc + diff --git a/admin-guide/legacy/misc/nxserverclientinstallation.rst b/admin-guide/legacy/misc/nxserverclientinstallation.rst new file mode 100644 index 00000000..e24abe47 --- /dev/null +++ b/admin-guide/legacy/misc/nxserverclientinstallation.rst @@ -0,0 +1,164 @@ +NX Server/Client Installation +============================= + +References +---------- + +- http://freenx.berlios.de/ + +- http://nomachine.com/ + +- http://wiki.centos.org/HowTos/FreeNX/ + + +Introduction +------------ + +This document describes the setup of an NX server/client +infrastructure on SL54. + +First, a more generic installation procedure is illustrated, second, +the PSI default nx server/client setup is shown. + +Generic Installation +-------------------- + +NX Server +~~~~~~~~~ + +Required Packages +................. + +- nx +- freenx + +The packages were found in the centos-extras repository. One can use +the following yum repo file, for instance. + +File `/etc/yum.repos.d/centos-extras.repo`:: + + [centos-extras] + name=Centos Extras for SL5.5 + baseurl=ftp://mirror.switch.ch/mirror/centos/5.5/extras/$basearch/ + enabled=0 + +Procedure +......... + +Install the required packages on your platform, i386 or x86_64:: + + # yum --enablerepo centos-extras install freenx + +Now, generate the ssh keys:: + + # nxkeygen + +The keys are stored in `/etc/nxserver` and in the home directory of +the nx user account:: + + # cd /var/lib/nxserver/home/ + # ls -l .ssh/ + -rw------- 1 nx root 672 Oct 22 16:28 authorized_keys2 + -rw------- 1 nx root 672 Oct 22 16:28 client.id_dsa.key + -rwx------ 1 nx root 392 Oct 22 16:14 known_hosts + -rw------- 1 nx root 605 Oct 22 16:28 server.id_dsa.pub.key + +The private key `client.id_dsa.key` has to be copied to the nx client +(see next section). + +NX Client +~~~~~~~~~ + +Required Packages +................. + +- nxclient + + +Procedure +......... + +NoMachine does not allow the distribution of their client, so it must +be downloaded from their website at http://nomachine.com/. + +After downloading install it:: + + # rpm -ivh nxclient-3.4.0-7.i386.rpm + +Get the private ssh key of user nx from the server and copy it to the +client:: + + # [root@server] + # scp /var/lib/nxserver/home/.ssh/client.id_dsa.key client:/usr/NX/share/keys/ + +Create the following symbolic link to the key on the client:: + + # [root@client] + # cd /usr/NX/share/keys/ + # ln -s client.id_dsa.key server.id_dsa.key + +Now, you can login to the nx server:: + + # nxclient + + +PSI Installation +---------------- + +The difference between the generic and the PSI installation is, that +the NX packages can be installed from our local repository. Further, +the PSI default keys are part of this installation, i.e. installing +the RPMS sets up a working NX server/client environment. + + +NX Server +~~~~~~~~~ + +Required Packages +................. + +- nx +- freenx +- freenx-psi + + +Currently the server packages are available from the SL54 psi-beta +repository, while the client packages are located in the PSI nonfree +repo. + +Procedure +......... + +File `/etc/yum.repos.d/psi-beta.repo`:: + + [psi-beta] + name=54 psi beta + baseurl=http://linux.web.psi.ch/dist/scientific/54/beta/ + enabled=0 + +Install freenx, nx and freenx-psi on the server:: + + # yum --enablerepo psi-beta install freenx nx freenx-psi + +NX Client +~~~~~~~~~ + +Required Packages +................. + +- nxclient +- nxclient-psi + + +Procedure +......... + +Install nxclient and nxclient-psi on the client host:: + + # yum install nxclient nxclient-psi + + +Now, you can login to the nx server:: + + # nxclient + diff --git a/admin-guide/legacy/misc/prepareanewslrelease.rst b/admin-guide/legacy/misc/prepareanewslrelease.rst new file mode 100644 index 00000000..24d70528 --- /dev/null +++ b/admin-guide/legacy/misc/prepareanewslrelease.rst @@ -0,0 +1,162 @@ +Prepare a new release +===================== + +Introduction +------------ + +This document describes the preparation of a new SLP major or minor +release for SL >= 5.4. + +Requirements +------------ + +Before you start you need a clean copy of the original SL repositories +of interest from http://www.scientificlinux.org. + +The SL repositories shall be mirrored to our AFS mirror on its own +volume, e.g. `/afs/psi.ch/software/mirror/scientific/54/` is on AFS +volume `sw.mirror.sl54.nb`. + +However, the mirror is usually made automatically by the script +`/afs/psi.ch/software/mirror/scripts/mirror.sh` which is run by cron +on pxeserv01. To add a new distribution to the mirror script you have +to edit the file `/afs/psi.ch/software/mirror/scripts/mirror.conf`. + +You also need a separate AFS distribution volume, e.g. `sw.dist.sl54` +for `/afs/psi.ch/software/linux/dist/scientific/54`. + +Once this is done, you're ready to start with the Procedure section. + + +Procedure +--------- + +1. Go to the SL distribution B directory, change to the + subdirectory `scripts` and run the following scripts:: + + # cd /afs/psi.ch/software/linux/dist/scientific/ + # cd scripts/Sl60/ + # sh 1-create_the_new_dist-config_file.sh + # sh 2-copy_the_kernel_and_initrd_for_tftp_boot.sh + # sh 3-copy_the_puppet_environment_for_desktop.sh # If a new one should be used, + # usually only for major release + # changes + # Note: Some of the files might need some manual customization, e.g. + # + # module_gdm (pictures) + # module_splash (pictures) + # module_background_image (pictures) + # module_buildsystem + + + # sh 4-create_new_dist_directory_structure.sh + + ### Check and edit the new files if necessary, especially the following ones: + # scripts/dist-config + # scripts/KERNEL_MODULES_TO_BUILD/sl6.i386.kms-to-be-built + # scripts/KERNEL_MODULES_TO_BUILD/sl6.x86_64.kms-to-be-built + # scripts/build-gpfs.sl6x.sh + # scripts/build-openafs.sl6x.i686.sh + # scripts/build-openafs.sl6x.x86_64.sh + # scripts/copy_the_sl_base_repos_from_the_local_mirror.sh + # scripts/rsync_security_updates_to_all_directories.sh + + is the distribution which serves as a template for + . + + The scripts will prepare most of the stuff automatically based on + the previous version. Some of the new files, however, still have to + be edited manually. + +2. Go to the SL distribution directory, change to the subdirectory + `scripts` and run the following scripts:: + + # cd /afs/psi.ch/software/linux/dist/scientific/60/scripts/ + + 2.1 Copy the SL Base Repos + + The script below copies the sl6base repository from the mirror on + AFS to the dist SL6 directory taking into account the + `rsync_exclude.rpmlist`, i.e. not all RPMS will be copied. To keep + the repodata consistent with the RPMS in the Packages directory, + the repodata has to be updated, too, by running the second script + shown here:: + + # sh copy_the_sl_base_repos_from_the_local_mirror.sh + # sh run_createrepo_on_base_i386.sh #sl64: still to do + # sh run_createrepo_on_base_x86_64.sh #sl64: still to do + + 2.2 Copy the Security Updates:: + + # sh rsync_security_updates_to_all_directories.sh + + 2.3 Build kernel module if minor release + + If you prepare a new major release skip this section. + + If you prepare a new minor release you already have build systems + where you can build kernel modules. + + Thus check whether you have to build at least the openafs and the + gpfs modules. If the kernel versions of this and the previous SL + minor versions do not differ you should already have the modules + copied to e.g. the nonfree and psi repos, then there's nothing to + do here. + + 2.4 Update The Symbolic Links in RPMS_all:: + + # sh update_symlinks_in_RPMS_all.sh + +3. Create new snaphots, release UNSTABLE and set the initial PSI + version. + + # ./create_new_snapshots.sh alldirs > \ + # INITIAL_LOG/2011-02-25-create_new_snapshots.log 2>&1 + # ./release_unstable.sh + # ./create_new_psi_version.sh + # ./create_file_psiversion-info.sh + +6. Write the new kickstart conig files. + + Goto the kickstart config directory and use one of the old + kickstart config files as a template:: + + # cd /afs/psi.ch/software/linux/kickstart/configs/ + +8. Make the new entries in the tftpd file. + + Goto the tftpd directory and edit the file default:: + + # cd /afs/psi.ch/service/linux/tftpboot/pxelinux.cfg/ + # vi default + + #<<< sl64: hereiam: + #<<< to do: fix /usr/bin/psi-fix_file_permission, module_localadmin + +9. Now perform first installation tests and debug where necessary. + +10. If you prepare a new major release, install new build systems. + +12. If you prepare a new major release, go to + `/afs/psi.ch/project/linux/dist` and create the directory + structure below for the RPM build environment:: + + slp6 + |-- RPMS/ + | |-- i386/ + | |-- i486/ + | |-- i586/ + | |-- i686/ + | |-- noarch/ + | `-- x86_64/ + `-- SRPMS/ + +14. Build kernel modules. + +15. Also get new software versions for non SL repos (psi, others, + etc.). + +16. Again create new snapshots and a new PSI version. + +17. Now perform the second test installation and debugging suite. + diff --git a/admin-guide/legacy/misc/projectpsi-puppet1.rst b/admin-guide/legacy/misc/projectpsi-puppet1.rst new file mode 100644 index 00000000..867a8f07 --- /dev/null +++ b/admin-guide/legacy/misc/projectpsi-puppet1.rst @@ -0,0 +1,1070 @@ +Project `psi-puppet1` +===================== + +Introduction +------------ + +This document describes the relaunch of the puppet service +infrastructure at PSI. + +The whole project can be divided into two parts: + +- The hard- and software setup for the puppet server and client. + (Described in this document.) + +- Implementation of the configuration for puppet clients. (Described + in [[PuppetManifestsForSL53][Puppet Manifests For SL53]].) + + +Objectives +---------- + +- To get a stable, scalable and easy to manage puppet service + infrastructure. + +- To gain a better overview of the various client configurations + configured by puppet. + +- To keep a clear and up-to-date documentation. + +- To keep the different configurations of the different SL releases + separated from each other, e.g. SL 5.1 does not overlap with SL 5.3. + +- Also other users from AIT and GFA than the puppet administrator + should have the possibility to use puppet to configure their hosts. + +- The different client configurations of the different puppet users + must not interfere with each other. + +- To manage the changes to manifests and client configuration files. + +- Easy recovery of files in case of data loss. + +- Easy and fast reinstallation of an identical puppet server in case + of an irreparable server crash. + + +Description of the Basic Server Setup +------------------------------------- + +- Hardware + + Dell Power Edge 1750 + +- Operating System + + SL51 32 bit Server + +- Network configuration + + Static IP for Production Server: 129.129.190.174/24 + Hostname: psi-puppet1.psi.ch + +- Required RPMS + + - puppet-server (http://download.fedora.redhat.com/pub/epel/5/i386/repoview/) + - augeas-libs + - facter + - puppet (http://download.fedora.redhat.com/pub/epel/5/i386/repoview/) + - ruby + - ruby-augeas + - ruby-libs + - ruby-shadow + - ruby-irb (required for reading help) + - ruby-rdoc (required for reading help) + + +Procedure +--------- + +Create a Repository for Puppet Related RPMS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +First make the directory in the SL51 installation tree:: + + # mkdir /afs/psi.ch/software/linux/dist/scientific/51/puppet-0247 + +Add the following RPMS to this repository and run `createrepo`:: + + puppet-server-0.24.7-4.el5.noarch.rpm + augeas-libs-0.3.5-1.el5.i386.rpm + facter-1.5.2-2.el5.noarch.rpm + puppet-0.24.7-4.el5.noarch.rpm + ruby-augeas-0.2.0-1.el5.i386.rpm + ruby-shadow-1.4.1-7.el5.i386.rpm + + # cd /afs/psi.ch/software/linux/dist/scientific/51/puppet-0247 + # createrepo . + +To enable the access to this repo create the yum repo file +`/etc/yum.repos.d/puppet-0247.repo` on the puppet server:: + + [puppet-0247] + name=puppet-0247 for SL5 + baseurl=http://linux.web.psi.ch/dist/scientific/5/puppet-0247/ + enabled=1 + + +Setup The Puppet Server +~~~~~~~~~~~~~~~~~~~~~~~ + +Basic Server Installation +......................... + +Install SL51, class Server via PXE boot and kickstart. + + +Puppet-Server Installation +.......................... + +Install `puppet-server` with yum. This will also draw the required +dependencies:: + + # [root@psi-puppet1] + # yum install puppet-server + + ... + Finished Kernel Module Plugin + + Dependencies Resolved + + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Installing: + puppet-server noarch 0.24.7-4.el5 puppet-0247 25 k + Installing for dependencies: + augeas-libs i386 0.3.5-1.el5 puppet-0247 151 k + facter noarch 1.5.2-2.el5 puppet-0247 41 k + puppet noarch 0.24.7-4.el5 puppet-0247 548 k + ruby i386 1.8.5-5.el5_2.6 sl5update 279 k + ruby-augeas i386 0.2.0-1.el5 puppet-0247 17 k + ruby-libs i386 1.8.5-5.el5_2.6 sl5update 1.6 M + ruby-shadow i386 1.4.1-7.el5 puppet-0247 9.5 k + + Transaction Summary + ============================================================================= + Install 8 Package(s) + Update 0 Package(s) + Remove 0 Package(s) + ... + + +Configure The Puppet Server +........................... + +The configuration files of the puppet server, directory +`/etc/puppet/`, are stored locally. + +The puppet client configuration files are stored on AFS. The mountpoint on +psi-puppet1 is `/var/puppet/environments`, thus +create the directory `/var/puppet/environments`. + + # mkdir -p /var/puppet/environments + +For how to mount the AFS see section `Mount AFS Volumes` below. + +The client configuration files in /var/puppet/environments are +described at [[PuppetManifestsForSL53][Puppet Manifests For SL53]]. + +The log is on the local disk in `/var/log/puppet`. +To set the logfile edit the line `PUPPETMASTER_OPTS` +in `/etc/rc.d/init.d/puppetmaster`. For testing also the +debug option `-d` is enabled:: + + PUPPETMASTER_OPTS="-v -d -l /var/log/puppet/puppetmaster.log" + +Config file `puppet.conf`:: + + ########################################################################### + # $Header: /etc/puppet/RCS/puppet.conf,v 1.3 2009/09/07 18:11:17 root Exp root $ + # + # Puppetmaster Environments + # ========================= + # + # Ref.: http://reductivelabs.com/trac/puppet/wiki/UsingMultipleEnvironments + # + # Marc Gasser, PSI + # last modified 2011-11-18 + # + ############################################################################ + [main] + # Where Puppet stores dynamic and growing data. + # The default value is '/var/puppet'. + vardir = /var/puppet + + # The Puppet log directory. + # The default value is '$vardir/log'. + # logdir = /afs/psi.ch/service/linux/puppet/var/log + logdir = /var/log/puppet + + # Where Puppet PID files are kept. + # The default value is '$vardir/run'. + rundir = /var/run/puppet + + # Where SSL certificates are kept. + # The default value is '$confdir/ssl'. + ssldir = $vardir/ssl + + # Whether log files should always flush to disk. + # The default value is false + autoflush = true + + + + [puppetmasterd] + reports = store + #reports = store , tagmail, rrdgraph + + # tagmap = $confdir/tagmail.conf + + #rrddir = $vardir/rrd + #rrdinterval = $runinterval + #rrdgraph = true + + [puppetd] + # The file in which puppetd stores a list of the classes + # associated with the retrieved configuratiion. Can be loaded in + # the separate ``puppet`` executable using the ``--loadclasses`` + # option. + # The default value is '$confdir/classes.txt'. + classfile = $vardir/classes.txt + + # Where puppetd caches the local configuration. An + # extension indicating the cache format is added automatically. + # The default value is '$confdir/localconfig'. + localconfig = $vardir/localconfig + + # Note: The port that the client daemon listens on, defaults to + # 8139. However, at PSI we run puppetd via the psi-puppet + # script with run onetime option enabled. + # psi-puppet is triggered by cron. + + ######################### + ####### SL 5 ######## + ######################### + + ### begin{ SL 5 (SL54), gasser_m + [DesktopSL5Unstable] + manifest = /var/puppet/environments/DesktopSL5Unstable/manifests/site.pp + modulepath = /var/puppet/environments/DesktopSL5Unstable/modules + + [ServerSL5Unstable] + manifest = /var/puppet/environments/ServerSL5Unstable/manifests/site.pp + modulepath = /var/puppet/environments/ServerSL5Unstable/modules + + [DesktopSL5Testing] + manifest = /var/puppet/environments/DesktopSL5Testing/manifests/site.pp + modulepath = /var/puppet/environments/DesktopSL5Testing/modules + + [DesktopSL5Stable] + manifest = /var/puppet/environments/DesktopSL5Stable/manifests/site.pp + modulepath = /var/puppet/environments/DesktopSL5Stable/modules + + [CPT] + manifest = /var/puppet/environments/CPT/manifests/site.pp + modulepath = /var/puppet/environments/CPT/modules + + ###}end SL 5 (SL54), gasser_m + + ### V.M. for sl53-c-ks.cfg + [CnodeSL5] + manifest = /var/puppet/environments/CnodeSL5/manifests/site.pp + modulepath = /var/puppet/environments/CnodeSL5/modules + + [PHServerSL5] + manifest = /var/puppet/environments/PHServerSL5/manifests/site.pp + modulepath = /var/puppet/environments/PHServerSL5/modules + + [EdgarDevelopment] + manifest = /var/puppet/environments/EdgarDevelopment/manifests/site.pp + modulepath = /var/puppet/environments/EdgarDevelopment/modules + + [DerekDevelopment] + manifest = /var/puppet/environments/DerekDevelopment/manifests/site.pp + modulepath = /var/puppet/environments/DerekDevelopment/modules + + [cray] + manifest = /var/puppet/environments/cray/manifests/site.pp + modulepath = /var/puppet/environments/cray/modules + + + ### begin Heiner{ + [HeinerDevelopment] + manifest = /var/puppet/environments/HeinerDevelopment/manifests/site.pp + modulepath = /var/puppet/environments/HeinerDevelopment/modules + [HeinerDevelopment54] + manifest = /var/puppet/environments/HeinerDevelopment54/manifests/site.pp + modulepath = /var/puppet/environments/HeinerDevelopment54/modules + [GFA] + manifest = /var/puppet/environments/GFA/manifests/site.pp + modulepath = /var/puppet/environments/GFA/modules + ### }end Heiner + + ### begin Rene{ + [GFADesktopSL5] + manifest = /var/puppet/environments/GFADesktopSL5/manifests/site.pp + modulepath = /var/puppet/environments/GFADesktopSL5/modules + + [GFADesktopSL6] + manifest = /var/puppet/environments/GFADesktopSL6/manifests/site.pp + modulepath = /var/puppet/environments/GFADesktopSL6/modules + ### }end Rene + + ### Services + [Web] + manifest = /var/puppet/environments/Web/manifests/site.pp + modulepath = /var/puppet/environments/Web/modules + + [Virtual] + manifest = /var/puppet/environments/Virtual/manifests/site.pp + modulepath = /var/puppet/environments/Virtual/modules + + [News] + manifest = /var/puppet/environments/News/manifests/site.pp + modulepath = /var/puppet/environments/News/modules + + [MySQL] + manifest = /var/puppet/environments/MySQL/manifests/site.pp + modulepath = /var/puppet/environments/MySQL/modules + + [Loadbalancer] + manifest = /var/puppet/environments/Loadbalancer/manifests/site.pp + modulepath = /var/puppet/environments/Loadbalancer/modules + + [LlcLoadbalancer] + manifest = /var/puppet/environments/LlcLoadbalancer/manifests/site.pp + modulepath = /var/puppet/environments/LlcLoadbalancer/modules + + [License] + manifest = /var/puppet/environments/License/manifests/site.pp + modulepath = /var/puppet/environments/License/modules + + [FTP] + manifest = /var/puppet/environments/FTP/manifests/site.pp + modulepath = /var/puppet/environments/FTP/modules + + [Elog] + manifest = /var/puppet/environments/Elog/manifests/site.pp + modulepath = /var/puppet/environments/Elog/modules + + [Cups] + manifest = /var/puppet/environments/Cups/manifests/site.pp + modulepath = /var/puppet/environments/Cups/modules + + [Archive] + manifest = /var/puppet/environments/Archive/manifests/site.pp + modulepath = /var/puppet/environments/Archive/modules + + + ######################### + ####### SL 6 ######## + ######################### + + ### begin{ SL 6 (gasser_m) + [DesktopSL6Unstable] + manifest = /var/puppet/environments/DesktopSL6Unstable/manifests/site.pp + modulepath = /var/puppet/environments/DesktopSL6Unstable/modules + + [DesktopSL6Testing] + manifest = /var/puppet/environments/DesktopSL6Testing/manifests/site.pp + modulepath = /var/puppet/environments/DesktopSL6Testing/modules + + [DesktopSL6Stable] + manifest = /var/puppet/environments/DesktopSL6Stable/manifests/site.pp + modulepath = /var/puppet/environments/DesktopSL6Stable/modules + + ###}end SL 6 (gasser_m) + + ### Markushin + [CnodeSL6] + manifest = /var/puppet/environments/CnodeSL6/manifests/site.pp + modulepath = /var/puppet/environments/CnodeSL6/modules + + +Config file `fileserver.conf`:: + + # This file consists of arbitrarily named sections/modules + # defining where files are served from and to whom + + # Define a section 'files' + # Adapt the allow/deny settings to your needs. Order + # for allow/deny does not matter, allow always takes precedence + # over deny + # [files] + # path /var/lib/puppet/files + # allow *.example.com + # deny *.evil.example.com + # allow 192.168.0.0/24 + + + #[facts] + # path /etc/puppet/facts + # allow *.psi.ch + + [GFA5] + path /afs/psi.ch/project/slscomp/puppet/gfa5 + allow *.psi.ch + + [GFA6] + path /afs/psi.ch/project/slscomp/puppet/gfa6 + allow *.psi.ch + + +Mount AFS Volumes on Puppet Server +.................................. + +The puppet manifests for clients are located on AFS:: + + /afs/psi.ch/service/linux/puppet/var/puppet/environments/ + +AFS is already mounted as `/afs` in this default SL5 server installation:: + + # mount + ... + AFS on /afs type afs (rw) + +Now, we want to remount +`/afs/psi.ch/service/linux/puppet/var/puppet/environments` on +`/var/puppet/environments`. Therefor the mount option `bind` is used, +which facilitates to remount parts of already mounted filesystems on +an alternative location in the file hierarchy. + +The server also needs the permission on AFS to mount the environments +directory. Add the new server to the AFS group +svc.linux:puppet_hosts:: + + # pts ad -u -g svc.linux:puppet_hosts + +As shown below we do the remount in `/etc/rc.local`, which is executed +after all the other init scripts:: + + #!/bin/sh + + touch /var/lock/subsys/local + + # Puppet + mount -o bind /afs/psi.ch/service/linux/puppet/etc/puppet/environments /var/puppet/environments + + # Restart Services depending on afs mounts + /etc/init.d/puppetmaster restart + +Before the `rc.local` script can be applied the proper AFS permissions +have to be set to make the files readable for psi-puppet1. This was +done already before, see topic +[[PuppetServerPsiPuppet2ForSl51#4_1_3_Mount_AFS_Volumes_on_Puppe][Puppet +Server Psi Puppet 2 For SL51]], so we only have to put the IP address +of psi-puppet1 to the AFS group `svc_linux:puppet_hosts`:: + + # pts adduser 129.129.190.174 svc_linux:puppet_hosts + +Configuring Puppet Reporting +............................ + +There are a number of different report processors available on the +puppetmaster. The default report, store, simply stores the report file +on the disk. + +By default, each client is configured not to report back to the +master. It has to be enabled either by the report option in +`puppet.conf` or using `--report` on the command line. + +`/etc/puppet/puppet.conf`:: + + [puppetd] + report = true + +Command line:: + + # puppetd --report + +Store Report Processor +,,,,,,,,,,,,,,,,,,,,,, + +Enable the store reports by using the `reports` +configuration option in the puppemasterd section of the +`puppet.conf` file on the master. + +`/etc/puppet/puppet.conf`:: + + [puppetmasterd] + reports = store + +The default reports directory is `$vardir/reports`. + +Tagmail Report Processor +,,,,,,,,,,,,,,,,,,,,,,,, + +Enable the tagmail reports by using the `reports` configuration option +in the puppemasterd section of the `puppet.conf` file on the +master. The `tagmail.conf` file contains a list of tags and email +adresses. The special tags all and err are defined implicitly. + +`/etc/puppet/puppet.conf`:: + + [puppetmasterd] + reports = tagmail + tagmap = $confdir/tagmail.conf + +`/etc/puppet/tagmail.conf`:: + + all: marc.gasser@psi.ch + err: marc.gasser@psi.ch + + +Rrdgraph Report Processors +,,,,,,,,,,,,,,,,,,,,,,,,,, + +To enable the `rrdgraph` reports, `rrdtool` and `rrdtool-ruby` +packages have to be installed. + +Download the packages from the following repository: +`/etc/yum.repos.d/epeli386.repo`:: + + [epeli386] + name=epel i386 + baseurl=http://download.fedora.redhat.com/pub/epel/5/i386/ + enabled=0 + + + # yumdownloader --enablerepo=epeli386 rrdtool.i386 rrdtool-ruby.i386 + # yum install rrdtool-1.2.27-3.el5.i386.rpm + # yum install rrdtool-ruby-1.2.27-3.el5.i386.rpm + +You might want to put them to your local repository, too. + +**Note**: For the time being put them to `psi-beta`, because they +break dependencies in the other repositories. + +Then, configure `puppet.conf` by adding the lines shown below in the +corresponding section. Here store, tagmail and rrdgraph are enabled. + +`/etc/puppet/puppet.conf`:: + + [puppetmasterd] + reports = store, tagmail, rrdgraph + + rrddir = $vardir/rrd + rrdinterval = $runinterval + rrdgraph = true + +Install The Ganglia Monitor Daemon +.................................. + +Install `ganglia-gmond-3.0.6-4.slp5` and add the configuration +`/etc/gmond.conf` file as shown below:: + + /* This configuration is as close to 2.5.x default behavior as possible + The values closely match ./gmond/metric.h definitions in 2.5.x */ + globals { + daemonize = yes + setuid = yes + user = nobody + debug_level = 0 + max_udp_msg_len = 1472 + mute = no + deaf = no + host_dmax = 0 /*secs */ + cleanup_threshold = 300 /*secs */ + gexec = no + } + + /* If a cluster attribute is specified, then all gmond hosts are wrapped inside + * of a tag. If you do not specify a cluster tag, then all will + * NOT be wrapped inside of a tag. */ + cluster { + name = "puppet" + owner = "unspecified" + latlong = "unspecified" + url = "unspecified" + } + + /* The host section describes attributes of the host, like the location */ + host { + location = "unspecified" + } + + /* Feel free to specify as many udp_send_channels as you like. Gmond + used to only support having a single channel */ + udp_send_channel { + mcast_join = 239.129.190.89 + port = 8649 + } + + /* You can specify as many udp_recv_channels as you like as well. */ + udp_recv_channel { + mcast_join = 239.129.190.89 + port = 8649 + bind = 239.129.190.89 + } + + # udp_recv_channel { + # host = "puppet" + # port = 8649 + # } + + /* You can specify as many tcp_accept_channels as you like to share + an xml description of the state of the cluster */ + tcp_accept_channel { + port = 8649 + } + + + /* The old internal 2.5.x metric array has been replaced by the following + collection_group directives. What follows is the default behavior for + collecting and sending metrics that is as close to 2.5.x behavior as + possible. */ + + /* This collection group will cause a heartbeat (or beacon) to be sent every + 20 seconds. In the heartbeat is the GMOND_STARTED data which expresses + the age of the running gmond. */ + collection_group { + collect_once = yes + time_threshold = 20 + metric { + name = "heartbeat" + } + } + + /* This collection group will send general info about this host every 1200 secs. + This information doesn't change between reboots and is only collected once. */ + collection_group { + collect_once = yes + time_threshold = 1200 + metric { + name = "cpu_num" + } + metric { + name = "cpu_speed" + } + metric { + name = "mem_total" + } + /* Should this be here? Swap can be added/removed between reboots. */ + metric { + name = "swap_total" + } + metric { + name = "boottime" + } + metric { + name = "machine_type" + } + metric { + name = "os_name" + } + metric { + name = "os_release" + } + metric { + name = "location" + } + } + + /* This collection group will send the status of gexecd for this host every 300 secs */ + /* Unlike 2.5.x the default behavior is to report gexecd OFF. */ + collection_group { + collect_once = yes + time_threshold = 300 + metric { + name = "gexec" + } + } + + /* This collection group will collect the CPU status info every 20 secs. + The time threshold is set to 90 seconds. In honesty, this time_threshold could be + set significantly higher to reduce unneccessary network chatter. */ + collection_group { + collect_every = 20 + time_threshold = 90 + /* CPU status */ + metric { + name = "cpu_user" + value_threshold = "1.0" + } + metric { + name = "cpu_system" + value_threshold = "1.0" + } + metric { + name = "cpu_idle" + value_threshold = "5.0" + } + metric { + name = "cpu_nice" + value_threshold = "1.0" + } + metric { + name = "cpu_aidle" + value_threshold = "5.0" + } + metric { + name = "cpu_wio" + value_threshold = "1.0" + } + /* The next two metrics are optional if you want more detail... + ... since they are accounted for in cpu_system. + metric { + name = "cpu_intr" + value_threshold = "1.0" + } + metric { + name = "cpu_sintr" + value_threshold = "1.0" + } + */ + } + + collection_group { + collect_every = 20 + time_threshold = 90 + /* Load Averages */ + metric { + name = "load_one" + value_threshold = "1.0" + } + metric { + name = "load_five" + value_threshold = "1.0" + } + metric { + name = "load_fifteen" + value_threshold = "1.0" + } + } + + /* This group collects the number of running and total processes */ + collection_group { + collect_every = 80 + time_threshold = 950 + metric { + name = "proc_run" + value_threshold = "1.0" + } + metric { + name = "proc_total" + value_threshold = "1.0" + } + } + + /* This collection group grabs the volatile memory metrics every 40 secs and + sends them at least every 180 secs. This time_threshold can be increased + significantly to reduce unneeded network traffic. */ + collection_group { + collect_every = 40 + time_threshold = 180 + metric { + name = "mem_free" + value_threshold = "1024.0" + } + metric { + name = "mem_shared" + value_threshold = "1024.0" + } + metric { + name = "mem_buffers" + value_threshold = "1024.0" + } + metric { + name = "mem_cached" + value_threshold = "1024.0" + } + metric { + name = "swap_free" + value_threshold = "1024.0" + } + } + + collection_group { + collect_every = 40 + time_threshold = 300 + metric { + name = "bytes_out" + value_threshold = 4096 + } + metric { + name = "bytes_in" + value_threshold = 4096 + } + metric { + name = "pkts_in" + value_threshold = 256 + } + metric { + name = "pkts_out" + value_threshold = 256 + } + } + + /* Different than 2.5.x default since the old config made no sense */ + collection_group { + collect_every = 1800 + time_threshold = 3600 + metric { + name = "disk_total" + value_threshold = 1.0 + } + } + + collection_group { + collect_every = 40 + time_threshold = 180 + metric { + name = "disk_free" + value_threshold = 1.0 + } + metric { + name = "part_max_used" + value_threshold = 1.0 + } + } + + # /etc/init.d/gmond start + + +See puppet at http://129.129.190.27/ganglia/. For the ganglia server +configuration ask Valeri Markushin. + + +Install The Networker Backup Client (Legato) +............................................ + +References: + +- [[http://ait.web.psi.ch/services/central_backup/][Information for Backup Client Administrators]] + +- [[http://ait.web.psi.ch/services/central_backup/nsr_install_lnx.html][Networker Client installation on Linux ]] + +Install the Networker client packages, the client itself and the +manual pages. By default `yum` calculates a lot of dependencies +required for the GUI of Networker, which facilitates the +restore. However, the restore can also be done using the command line +interface, thus the whole X installation shall be skipped. To do so, +the packages have to be installed without dependencies. + +Because `yum` does not provide an installation without dependencies, +`yumdownloader` is used to fetch the packages and `rpm -i --nodeps` to +install them. + +First install `yumdownloader`:: + + # yum install yum-utils + +Install the rest:: + + # yumdownloader --enablerepo=psi-beta lgtoclnt.i686 lgtoman.i686 + # rpm -ivh --nodeps lgtoclnt-7.4.2-1.i686.rpm lgtoman-7.4.2-1.i686.rpm + +Start the Networker daemon:: + + # service networker start + +The `/nsr` directory is automatically created. Add the string +`bs1.psi.ch` in the file `/nsr/res/server`. + +Restart the Networker daemon:: + + # service networker stop + # service networker start + +Now, contact the backup server administrator, Marco Kohler, so he can +add the host and the directories of interest to the backup service. + +The next steps are for facilitating the task of the backup server +administrator. + +Create the file `~/nsradmin74_x.txt` with the following three lines:: + + update administrator:"isroot,host=psi-puppet1","isroot,host=localhost","isroot,host=bs1","user=root,host=localhost","user=administrator,host=bs1" + . type: NSR System Port Ranges + update administrator:"isroot,host=psi-puppet1","isroot,host=localhost","isroot,host=bs1","user=root,host=localhost","user=administrator,host=bs1" + + +Then execute the command below and check the output:: + + # nsradmin -i ~/nsradmin74_x.txt -p nsrexec + + updated resource id 3.0.104.17.41.235.57.74.129.129.190.174(7) + updated resource id 9.0.104.17.41.235.57.74.129.129.190.174(2) + updated resource id 8.0.168.18.5.236.57.74.129.129.190.174(2) + updated resource id 9.0.168.18.5.236.57.74.129.129.190.174(2) + Current query set + updated resource id 7.0.104.17.41.235.57.74.129.129.190.174(2) + + +Finally, test if the installation was successful:: + + # service networker stop + # service networker start + # service networker status + +--o nsrexecd (5995) + +**Note**: Open files will not necessarily be considered during the +backup run. It depends on their locking state. + + +How To Update the Networker Backup Client +......................................... + +Because the Networker RPM is not cleanly packed, updating the client +requires deinstallation of the old and installation of the new +package. + +First the old `/nsr` directory has to be deleted. Then repeat the +whole procedure shown in the previous section. + +The Networker Administration Program +.................................... + +To start the Networker administration shell type the following +command:: + + # nsradmin -p nsrexec + +The Networker Recover Tool +.......................... + +Check out the manpage of `recover`:: + + # man recover + + +Setup The Puppet Client +~~~~~~~~~~~~~~~~~~~~~~~ + +At this time the only difference between the old and the new client +configuration is the name of the puppet server in the file +`/etc/puppet/puppet.conf`, `psi-puppet1` instead of `pxeserv01`. + +File `/etc/puppet/puppet.conf` on `vmmarctest1.psi.ch`:: + + [main] + vardir = /var/puppet + logdir = /var/log/puppet + rundir = /var/run/puppet + ssldir = $vardir/ssl + environment = development + + [puppetd] + classfile = $vardir/classes.txt + localconfig = $vardir/localconfig + factsync = true + server = psi-puppet1.psi.ch + + +Because the new puppet server refers to the same sources (files) as +the current productive server, we set the immutable to the file above, +otherwise next time `puppetd` is running the server entry will be +changed to `pxeserv01` again. + +The sources are located at +`/afs/psi.ch/software/linux/dist/scientific/51/puppet/files/` on +AFS. This path is set in the file `/etc/puppet/fileserver.conf` on the +puppet server. + +Make First Tests +~~~~~~~~~~~~~~~~ + +Start the puppetmaster:: + + # /etc/init.d/puppetmaster start + +Test it with a client (the options are: keep process in the +foreground, run onetime and be verbose):: + + # [root@vmmarctest1 ~] + # puppetd --no-daemonize -o -v + +Or run the client in no operational mode, i.e. dry runs without +actually applying the configuration:: + + # puppetd --noop --no-daemonize -o -v + + info: Loading fact sysconfig_psi + info: Loading fact sysconfig_psi-gfa + info: Creating a new certificate request for vmmarctest1.psi.ch + info: Creating a new SSL key at /var/puppet/ssl/private_keys/vmmarctest1.psi.ch.pem + warning: peer certificate won't be verified in this SSL session + notice: Got signed certificate + info: Retrieving facts + info: Loading fact sysconfig_psi + info: Loading fact sysconfig_psi-gfa + info: Caching catalog at /var/puppet/localconfig.yaml + notice: Starting catalog run + notice: //Node[default]/psi_localadmin/Exec[/usr/bin/psi-fix_file_permission >/dev/null]/returns: executed successfully + info: Filebucket[/var/puppet/clientbucket]: Adding /usr/share/texmf/dvips/config/config.ps(1611c4bb4b35341f1945059ff774c6df) + notice: //Node[default]/psi_base/File[/usr/share/texmf/dvips/config/config.ps]: Filebucketed to with sum 1611c4bb4b35341f1945059ff774c6df + notice: //Node[default]/psi_base/File[/usr/share/texmf/dvips/config/config.ps]/source: replacing from source puppet://psi-puppet1.psi.ch/51/Desktop/usr/share/texmf/dvips/config/config.ps with contents {md5}b265606dc098a5414f3acd71a8831ef1 + notice: //Node[default]/psi_puppet/File[/etc/puppet/puppet.conf]/checksum: checksum changed '{md5}f2944bb81bfbe22b2a2ac4c9197563f3' to '{md5}be67850ccad5409063a56de9d5a516d3' + notice: //Node[default]/psi_puppet/File[/etc/puppet/puppet.conf]: Filebucketed to with sum be67850ccad5409063a56de9d5a516d3 + err: //Node[default]/psi_puppet/File[/etc/puppet/puppet.conf]: Could not rename tmp /etc/puppet/puppet.conf for replacing: Operation not permitted - /etc/puppet/puppet.conf.puppettmp or /etc/puppet/puppet.conf + notice: //Node[default]/psi_puppet/File[/etc/puppet/puppet.conf]/source: replacing from source puppet://psi-puppet1.psi.ch/51/Desktop/etc/puppet/puppet.conf.testing with contents {md5}f2944bb81bfbe22b2a2ac4c9197563f3 + info: Filebucket[/var/puppet/clientbucket]: Adding /etc/sysctl.conf(d5716d328f5b840eb4e13ae1d2896fe9) + notice: //Node[default]/psi_base/File[/etc/sysctl.conf]: Filebucketed to with sum d5716d328f5b840eb4e13ae1d2896fe9 + notice: //Node[default]/psi_base/File[/etc/sysctl.conf]/source: replacing from source puppet://psi-puppet1.psi.ch/51/Desktop/etc/sysctl.conf with contents {md5}d576ff606d3f93df26965e7ef364bd07 + notice: //Node[default]/psi_yum/Exec[/usr/sbin/psi-get-yumconf]/returns: executed successfully + notice: Finished catalog run in 6.22 seconds + + +So, this looks promising. Seems like the client could get it's +configuration from the new puppet server. + +Only the file `/etc/puppet/puppet.conf` could not be changed, what is +ok because the immutable flag was set. + +Next Steps +---------- + +- Verify migration order (server, client or vice versa) + +- Finalize basic server setup (verify that no config agents compromise + the system, e.g. puppetd which could be executed by cron or during + boot time, etc.), check whether it makes sense to use DNS aliases + for the hostname. + +- Shall server configuration files be stored locally or mounted from + AFS? + + +`psi-puppet1:/etc/rc.d/rc.local` has been prepared (not activated yet) +for the AFS mount:: + + #!/bin/sh + # + # This script will be executed *after* all the other init scripts. + # You can put your own initialization stuff in here if you don't + # want to do the full Sys V style init stuff. + + touch /var/lock/subsys/local + + # Puppet + #mount -o bind /afs/psi.ch/service/linux/puppet/etc/puppet-0.24.7-4 /etc/puppet + + # Restart Services depending on afs mounts + #/etc/init.d/puppetmaster restart + +The whole current puppetserver configuration from /etc/puppet/ was +copied to `/afs/psi.ch/service/linux/puppet/etc/puppet-0.24.7-4`. + +- If mounted from AFS the question remains how root@psi-puppet1 gets + the permission to mount the mentioned AFS directory. + +- Shall the client configuration manifests be stored locally or on + AFS? + + +Locally: `/var/puppet/environments/` + +AFS: `/afs/psi.ch/service/linux/puppet/etc/puppet-0.24.7-4/environments/` + +- Run the puppetmaster on hardware or vmware? Hardware. + +- When the server is going to production the IP has to be changed, see + *Static IP for Production Server* above. Done. + +- When the server is going to production the PSI firewall has to be + adjusted. (Refer to Tobias) + +- Test with old client to new server, and new client to old server. + +- Test with limited number of new client to new server. diff --git a/admin-guide/legacy/misc/psi-puppet2_installation.rst b/admin-guide/legacy/misc/psi-puppet2_installation.rst new file mode 100644 index 00000000..7acf68e5 --- /dev/null +++ b/admin-guide/legacy/misc/psi-puppet2_installation.rst @@ -0,0 +1,609 @@ +Installation `psi-puppet2` +========================== + +References +---------- + +- https://wiki.intranet.psi.ch/AIT/PuppetServer2009 + +- http://reductivelabs.com/trac/puppet/wiki/PluginsInModules + + +Introduction +------------ + +This document describes the Installation of the new puppet server +psi-puppet2, which replaces the puppet server running on pxeserv01. + +The psi-puppet2 server is an interim solution for the pxeserv01 +replacement for the following reasons: + +- The puppet service on pxeserv01 is very unstable. + +- The performance on pxeserv01 is very bad, what makes work almost impossible. + +- The psi-puppet1 server is not ready for production yet. + +The new system will be setup as a 32 bit SL5 server with the latest +puppet server package and dependencies installed. + +The puppet server configuration is the same as the one on pxeserv01. + +**Note**: Don't confuse psi-puppet2 with psi-puppet1, which not only +is thought as a replacement of the puppet server on pxeserv01 but also +comes with a reimplementation of the whole puppet configuration, +whereas psi-puppet2 takes over the puppet configuration from +pxeserv01. + + +Description of the Basic Server Setup +------------------------------------- + +- Hardware + + Dell Power Edge 1750 + +- Operating System + + SL51 32 bit Server + +- Network configuration + + Static IP for Production Server: 129.129.190.160/24 + Hostname: psi-puppet2.psi.ch + +- Required RPMS + + - puppet-server (http://download.fedora.redhat.com/pub/epel/5/i386/repoview/) + - augeas-libs + - facter + - puppet (http://download.fedora.redhat.com/pub/epel/5/i386/repoview/) + - ruby + - ruby-augeas + - ruby-libs + - ruby-shadow + - ruby-irb (required for reading help) + - ruby-rdoc (required for reading help) + + +Procedure +--------- + +Setup The Puppet Server +~~~~~~~~~~~~~~~~~~~~~~~ + +Install The Puppet Server Software +.................................. + +Use the yum repositories `/etc/yum.repos.d/epeli386.repo` and +`/etc/yum.repos.d/epelx86_64.repo` to download and install the latest +puppet packages:: + + [epeli386] + name=epel i386 + baseurl=http://download.fedora.redhat.com/pub/epel/5/i386/ + enabled=0 + + +Install the puppet-server package. Dependencies will be resolved:: + + # yum --enablerepo=epeli386 install puppet-server + + ... + Dependencies Resolved + + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Installing: + puppet-server noarch 0.24.8-1.el5.1 epel 26 k + Installing for dependencies: + augeas-libs i386 0.5.1-1.el5 epel 196 k + facter noarch 1.5.5-1.el5 epel 54 k + puppet noarch 0.24.8-1.el5.1 epel 542 k + ruby i386 1.8.5-5.el5_2.6 sl5update 279 k + ruby-augeas i386 0.2.0-1.el5 epel 17 k + ruby-libs i386 1.8.5-5.el5_2.6 sl5update 1.6 M + ruby-shadow i386 1.4.1-7.el5 epel 9.5 k + + Transaction Summary + ============================================================================= + Install 8 Package(s) + Update 0 Package(s) + Remove 0 Package(s) + ... + + +For later use, download the required RPMS and copy them to our yum +repository, see section `Put Puppet Related RPMS To Our Yum +Repository` below. + + +Configure The Puppet Server +........................... + +Use the puppet server configuration of pxeserv01 on psi-puppet2. + +The configuration files of the puppet server, directory +`/etc/puppet/`, are located on AFS, see section `Mount AFS Volumes`. + +The log is on the local disk in `/var/log/puppet`. To set the logfile +edit the line `PUPPETMASTER_OPTS` in +`/etc/rc.d/init.d/puppetmaster`. For testing also the debug option +`-d` is enabled:: + + PUPPETMASTER_OPTS="-v -d -l /var/log/puppet/puppetmaster.log" + +Enable puppetmaster in runlevels 3, 4 and 5:: + + # chkconfig --levels 345 puppetmaster on + + +Mount AFS Volumes on Puppet Server +.................................. + +The puppet server configuration files as well as the puppet manifests +for clients are located on AFS. + +AFS is already mounted as `/afs` in this default SL5 server installation:: + + # mount + ... + AFS on /afs type afs (rw) + +Now, we want to remount `/afs/psi.ch/service/linux/puppet/etc/puppet` +on `/etc/puppet`. Therefor the mount option `bind` is used, which +facilitates to remount parts of already mounted filesystems on an +alternative location in the file hierarchy. + +As shown below we do the remount in `/etc/rc.local`, which is executed +after all the other init scripts:: + + #!/bin/sh + + touch /var/lock/subsys/local + + # Puppet + mount -o bind /afs/psi.ch/service/linux/puppet/etc/puppet /etc/puppet + + # Restart Services depending on afs mounts + /etc/init.d/puppetmaster restart + +Before the `rc.local` script can be applied the proper AFS permissions +have to be set. + +Check the AFS permissions:: + + # [gasser_m@pc7377 ~] + # fs la /afs/psi.ch/service/linux/ + + Access list for /afs/psi.ch/service/linux/ is + Normal rights: + svc_linux:tools l + svc_linux:puppet l + svc_linux:readonly rl + svc_linux:pxe l + svc_linux rlidwka + + +Create a new AFS group for the puppet server:: + + # pts creategr svc_linux:puppet_hosts -owner svc_linux + group svc_linux:puppet_hosts has id -10851 + +Add the IP of psi-puppet2 to this group:: + + # pts adduser 129.129.190.160 svc_linux:puppet_hosts + +Set the AFS permissions:: + + # fs sa /afs/psi.ch/service/linux/ svc_linux:puppet_hosts l + # fs sa /afs/psi.ch/service/linux/puppet/ svc_linux:puppet_hosts rl + # fs sa /afs/psi.ch/service/linux/puppet/etc svc_linux:puppet_hosts rl + # fs sa /afs/psi.ch/service/linux/puppet/var svc_linux:puppet_hosts rl + # fs sa /afs/psi.ch/service/linux/puppet/etc/puppet svc_linux:puppet_hosts rl + +Recursively set the same permissions to all subdirectories underneath +`/afs/psi.ch/service/linux/puppet/etc/puppet`:: + + # cd /afs/psi.ch/service/linux/puppet/etc/puppet + # find -noleaf -type d -exec fs sa {} svc_linux:puppet_hosts rl \; + +Then restart the AFS service:: + + # service afs restart + +Finally, run the `rc.local` script or just reboot psi-puppet2 to see +whether everything comes up. + + +Allow User Login Access To psi-puppet2 +...................................... + +To enable remote login via ssh and execution of root commands via +sudo, the following files have to be edited. + +- `/etc/passwd` + +- `/etc/shadow` + +- `/etc/security/ssh.allow` + +- `/etc/group` + +- `/etc/hosts.allow` + +- `/etc/sudoers` + + +passwd:: + + gasser_m:!:2374:840:Gasser Marc:/afs/psi.ch/user/g/gasser_m:/bin/bash + kapeller:!:3804:9102:Rene Kapeller:/afs/psi.ch/user/k/kapeller:/bin/bash + billich:!:3830:840:Heinrich Billich:/afs/psi.ch/user/b/billich:/bin/bash + markushin:!:3883:840:Valeri Markushin:/afs/psi.ch/user/m/markushin:/bin/bash + +shadow:: + + gasser_m:NP::::::: + kapeller:NP::::::: + billich:NP::::::: + markushin:NP::::::: + +group:: + + ait::840 + sls::9102 + +ssh.allow:: + + kapeller + billich + markushin + gasser_m + +hosts.allow:: + + sshd: ... pc7377 pc7377.psi.ch gfalc05 gfalc05.psi.ch pc4568 pc4568.psi.ch + + +Configuring Puppet Reporting +............................ + +There are a number of different report processors available on the +master. The default report, store, simply stores the report file on +the disk. + +By default, each client is configured not to report back to the +master. It has to be enabled either by the report option in +`puppet.conf` or using `--report` on the command line. + +`/etc/puppet/puppet.conf`:: + + [puppetd] + report = true + + +Command line:: + + # puppetd --report + + +Store Report Processor +,,,,,,,,,,,,,,,,,,,,,, + +Enable the store reports by using the `reports` configuration option +in the puppemasterd section of the `puppet.conf` file on the master. + +`/etc/puppet/puppet.conf`:: + + [puppetmasterd] + reports = store + +The default reports directory is $vardir/reports. + +Rrdgraph Report Processor +,,,,,,,,,,,,,,,,,,,,,,,,, + +To enable the `rrdgraph` reports, `rrdtool` and `rrdtool-ruby` +packages have to be installed. + +The packages are available from the the `psi-beta` repository, they +originate from the repository shown below. + +`/etc/yum.repos.d/epeli386.repo`:: + + [epeli386] + name=epel i386 + baseurl=http://download.fedora.redhat.com/pub/epel/5/i386/ + enabled=0 + + # yum install rrdtool rrdtool-ruby + +Then, configure `puppet.conf` by adding the lines shown below in the +corresponding section. Here store and rrdgraph are enabled. + +`/etc/puppet/puppet.conf`:: + + [puppetmasterd] + reports = store,rrdgraph + rrddir = $vardir/rrd + rrdinterval = $runinterval + rrdgraph = true + +Install the Ganglia Monitor Daemon +.................................. + +Install `ganglia-gmond` and add the configuration file shown below:: + + # yum install ganglia-gmond + +Use the same `/etc/gmond.conf` as on psi-puppet1:: + + # /etc/init.d/gmond start + +For the ganglia server configuration ask Valeri Markushin. + +See puppet at [[http://129.129.190.27/ganglia/][http://129.129.190.27/ganglia/]]. + +Setup The Puppet Client +~~~~~~~~~~~~~~~~~~~~~~~~ + +Either install or update the puppet package on a client:: + + # yum --enablerepo=psi-beta install puppet + + # yum --enablerepo=psi-beta update puppet + +Test The Puppet Clients +~~~~~~~~~~~~~~~~~~~~~~~ + +To find out which versions of puppet servers and clients are +compatible to each other and in which order they should be updated, +the following tests are performed. + + +Test the Old Client With The New Server +....................................... + +Set the new server `psi-puppet2.psi.ch` in `/etc/puppet/puppet.conf`, +remove the certificate and run puppetd:: + + # [root@vsl5132de-ut] + # cd /var/puppet/ + # rm -rf ssl/ + # puppetd --test + +Ok. + + +Test the New Client With The New Server +....................................... + +Update the puppet client. Set the new server `psi-puppet2.psi.ch` in +`/etc/puppet/puppet.conf`, remove the certificate and run puppetd:: + + # [root@vsl5132de-ut] + # yum --enablerepo=psi-beta update puppet + + # cd /var/puppet/ + # rm -rf ssl/ + # puppetd --test + +Ok. + + +Test the New Client With The Old Server +....................................... + +Update the puppet client. Then set the old server `pxeserv01.psi.ch` +in `/etc/puppet/puppet.conf`, remove the certificate and run puppetd:: + + # [root@vsl5132de-ut] + # yum --enablerepo=psi-beta update puppet + + ... + ============================================================================= + Package Arch Version Repository Size + ============================================================================= + Updating: + puppet noarch 0.24.8-1.el5.1 psi-beta 542 k + Installing for dependencies: + augeas-libs i386 0.5.1-1.el5 psi-beta 196 k + ruby-augeas i386 0.2.0-1.el5 psi-beta 17 k + ruby-shadow i386 1.4.1-7.el5 psi-beta 9.5 k + Updating for dependencies: + facter noarch 1.5.5-1.el5 psi-beta 54 k + + Transaction Summary + ============================================================================= + Install 3 Package(s) + Update 2 Package(s) + Remove 0 Package(s) + ... + + # cd /var/puppet/ + # rm -rf ssl/ + # puppetd --test + +Not ok. A lot of error messages appear. It seems the new client is not +compatible to the old server! + +Conclusion +.......... + +First update the server, then the client. + +So, when you have an old client addressing the new server for tests, +and finally you wanna change it back to the old server, this should +work by just modifying `/etc/puppet/puppet.conf` on the client. + +However, once you updated the client you can not go back to the old +server, unless you downgrade the client --- with yum this means +removing the new client and reinstalling the old one. + +Put Puppet Related RPMS To Our Yum Repository +--------------------------------------------- + +To have a consistent puppet installation on our hosts we put them to +our repository. + +Use yumdowloader, package yum-utils, to download puppet related RPMS:: + + # root@psi-puppet2 + # yum install yum-utils + + # yumdownloader --enablerepo=epeli386 puppet-server augeas-libs facter \ + # puppet ruby-augeas ruby-shadow + + # yumdownloader --enablerepo=epelx86_64 augeas-libs ruby-augeas ruby-shadow + + +**Note**: There seem to be only i386 and noarch versions of the + required RPMS. + +Before they are linked into the latest `testing` and `current` +repositories they should be tested. So copy them to the `psi-beta` +repository first:: + + # scp *rpm gasser_m@tux50:/afs/psi.ch/software/linux/dist/scientific/51/beta + + # gasser_m@tux50 + # cd /afs/psi.ch/software/linux/dist/scientific/51/beta + # createrepo . + +To test the puppet clients see section `Test The Puppet Clients`. + +If the tests passed successfully copy them to the `others` repository +and create symbolic links to `testing` and `current` to make them +available:: + + # [root@psi-puppet2] + # scp *rpm gasser_m@tux50:/afs/psi.ch/software/linux/dist/scientific/51/others/all + + # gasser_m@tux50 + # cd /afs/psi.ch/software/linux/dist/scientific/51/others/all + # createrepo . + + +Update Puppet +------------- + +Keep the following order. + +- Update the puppet server. + +- Update the puppet client. + + +Update The Puppet Server +~~~~~~~~~~~~~~~~~~~~~~~~ + +At the time of writing the latest Puppet version 0.25.1 was only +available at http://tmz.fedorapeople.org/repo/puppet/epel/5/i386/. + +Download the required packages to SL51 psi-beta repository first:: + + # wget http://tmz.fedorapeople.org/repo/puppet/epel/5/i386/puppet-server-0.25.1-0.3.el5.noarch.rpm + # wget http://tmz.fedorapeople.org/repo/puppet/epel/5/i386/puppet-0.25.1-0.3.el5.noarch.rpm + +Then login to a test server and stop the puppetmaster daemon:: + + # /etc/init.d/puppetmaster stop + +Because the /etc/puppet/ is on AFS, root has no write permissions. +So, first umount the etc/puppet from AFS, then run `yum update` using +the psi-beta repository, and remount etc/puppet:: + + # umount /etc/puppet + # yum --enablerepo=psi-beta update puppet-server + # mount -o bind /afs/psi.ch/service/linux/puppet/etc/puppet /etc/puppet + +Set the following options in /etc/init.d/puppetmaster:: + + PUPPETMASTER_OPTS="-v -d -l /var/log/puppet/puppetmaster.log" + +Finally, restart the service and test it with a client:: + + # /etc/init.d/puppetmaster start + +Login to a client and run puppetd:: + + # puppetd --test + +Update The Puppet Client +~~~~~~~~~~~~~~~~~~~~~~~~ + +Basically, the 0.24.x clients should be compatible to the 0.25.x +server. Though, there are some changes between the versions, that +might cause troubles. Thus, the puppet clients should be updated, too. + +On a SL51 client run:: + + # yum --enablerepo=psi-beta update puppet + +On a SL54 client run:: + + # yum update puppet + +As soon as the client is updated, its `puppet.conf` needs some +modifications, because of the "factsync" option which is deprecated +and replaced by "pluginsync" in the 0.25.x versions. + +`/etc/puppet/puppet.conf` on a 0.25.x client: "factsync" is replaced +by "pluginsync", factpath is set (not clear whether the latter is +necessary):: + + [main] + vardir = /var/puppet + logdir = /var/log/puppet + rundir = /var/run/puppet + ssldir = $vardir/ssl + pluginsync = true + factpath = $vardir/lib/facter + environment = DesktopSL5Unstable + + [puppetd] + report = true + classfile = $vardir/classes.txt + localconfig = $vardir/localconfig + server = psi-puppet1.psi.ch + + +Further the directory structure on the server for placing facts +changed. The new structure if using modules and environments is +illustrated below taking the environment "DesktopSL5Unstable" as an +example: + +The modulepath for DesktopSL5Unstable is:: + + modulepath = /var/puppet/environments/DesktopSL5Unstable/modules + +A stub module called "custom" has to be created in the "$modulepath" +subdirectory to keep the files:: + + $modulepath/custom/ + `-- lib/ + |-- facter/ + | `-- sysconfig_psi_desktop.rb + `-- puppet/ + |-- provider/ + `-- type/ + +This subdirectory tree under custom is implicitly searched by the +puppet server. + +**Notes**: + +If you have both, the new and the old variant to keep facts, option +"pluginsync" enabled, only the new script location will be considered. + +If you run only the old variant to keep facts:: + + $modulepath/facts/files/somescript.rb + +with option "factsync" enabled, they will be loaded giving out a +warning "... use pluginsync instead of factsync ..." + +For more information see the +http://reductivelabs.com/trac/puppet/wiki/PluginsInModules. diff --git a/admin-guide/legacy/misc/puppet-trouble-shooting-in-twiki.rst b/admin-guide/legacy/misc/puppet-trouble-shooting-in-twiki.rst new file mode 100644 index 00000000..35b093d7 --- /dev/null +++ b/admin-guide/legacy/misc/puppet-trouble-shooting-in-twiki.rst @@ -0,0 +1,145 @@ +Puppet Trouble-shooting in TWiki +================================ + +Introduction +------------ + +This is the location were to post puppet problems and solutions at AIT +and GFA. + +Please use the following format according the first entry below: + +- HEADING2: Error (HOSTNAME): "BEGIN OF ERROR MESSAGE ..." + *(The HOSTNAME in parentheses is optional, if the problem might affect any host.)* + +- HEADING3: Context, a short description in what situation the error appears. + +- HEADING3: Solution, if known, provide a possible solution to fix the problem. + + +Puppet Server Errors +-------------------- + +Error (pxeserv01): "Starting puppetmaster: Could not prepare for execution ..." +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Context +....... + +The puppetmaster daemon on pxeserv01 received an unattended SIGTERM +and stopped. Maybe there is a self signed certificate which expired +or something. Anyway, restarting failed showing the following error:: + + # [root@pxeserv01 puppet]# /etc/init.d/puppetmaster start + Starting puppetmaster: Could not prepare for execution: Retrieved certificate does not \ + match private key; please remove certificate from server and regenerate it with the current key + + +Solution +........ + +Create a new certificate for the server. + +**IMPORTANT NOTE**: Recreating a new certificate for the server showed +that the clients which still have the old certificate of the server +can not connect anymore to it. Thus you need to be sure you have a +way to update the certificate of the server on the clients before +applying this. Eventually, a better solution might be to just sign +the old server certificate with `puppetca`. It was not tested whether +this works, too. + +Remove /var/puppet/ssl/ on the server:: + + # rm -rf /var/puppet/ssl/ + + +Then try to start puppetmaster, what failed again, but recreated the +ssl subdirectory and its content:: + + # /etc/init.d/puppetmaster start + + +Eventually, sign the certificate for pxeserv01 itself:: + + # puppetca --sign pxeserv01.psi.ch + # /etc/init.d/puppetmaster start + + +Via our management console the certificates on the clients had to be +deleted, in order they can retrieve the new server certificate:: + + # for i in host1 host2 ... + # do + # ssh -o ConnectTimeout=1 root@$i rm -rf /var/puppet/ssl/ + # done + + +Puppet Client Errors +-------------------- + +Error: "Could not request certificate: ..." +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Context +....... + +Running puppetd on any client might fail showing the following error:: + + # puppetd --test + err: Could not request certificate: Retrieved certificate does not match private key; + please remove certificate from server and regenerate it with the current key + Exiting; failed to retrieve certificate and watiforcert is disabled + + +Solution +........ + +The problem is that for what reason ever the client certificate is not +valid, i.e. it does not match its copy stored on the puppet server. + +Usually this happens when a host is reinstalled keeping its original +hostname. During the initial puppetd run, the client requests a new +certificate from the server, which denies, because there is already a +certificate on the server for that hostname. + +To fix this you have to delete the old certificate on client and +server. + +On the server:: + + # puppetca --clean HOSTNAME.psi.ch + HOSTNAME.psi.ch + notice: Removing file Puppet::SSL::Certificate HOSTNAME.psi.ch at + '/var/puppet/ssl/ca/signed/mpc1273.psi.ch.pem' + +If this notice does not appear, the certificate was not deleted. + +On the client:: + + # rm -rf /var/puppet/ssl/ + +Then, run puppetd again:: + + # puppetd --test + + +Error: "notice: Run of Puppet configuration client already in progress; skipping ..." +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Context +....... + +Running puppetd on any client might fail showing the following error, +even `ps ax | grep puppetd` does not show a running puppet process:: + + # puppetd --test + notice: Run of Puppet configuration client already in progress; skipping + + +Solution +........ + +There is still an old lock file `/var/puppet/state/puppetdlock`. +Remove the lock file and run puppetd again:: + + # rm /var/puppet/state/puppetdlock diff --git a/admin-guide/legacy/misc/puppetmanifestsforsl53.rst b/admin-guide/legacy/misc/puppetmanifestsforsl53.rst new file mode 100644 index 00000000..8720b24d --- /dev/null +++ b/admin-guide/legacy/misc/puppetmanifestsforsl53.rst @@ -0,0 +1,98 @@ +Puppet Manifests for SL 5.3 +=========================== + + +Introduction +------------ + +As we are planning to upgrade from SL 5.1 to SL 5.3, we decided to +reorganize and reimplement all the client configuration manifests. + + +Procedure +--------- + +**Note**: Here we are still in the development state, thus filenames +and everything probably will be changed for the productive setup. + + +Puppet SVN +~~~~~~~~~~ + +To manage the changes to manifests and client configuration files we +use `subversion (svn)` as a revision control:: + + # ENV=CnodeSL5 + # mkdir /var/puppet/environments/$ENV + # cd /var/puppet/environments/$ENV + + +Check out all manifests:: + + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/manifests + + +Check out modules individually:: + + # mkdir /var/puppet/environments/$ENV/modules + # cd /var/puppet/environments/$ENV/modules + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/Modules/facts + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/Modules/cnode + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/Modules/psibasic + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/Modules/ssh + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/Modules/ntp + # svn co svn+ssh://svn.psi.ch/repos/linux/kickstart/trunk/puppet/Modules/scratch + + +On the Puppet Server Side +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Restart the puppet server. For testing use some increased verbosity +(-v), debug mode (-d) and log to a file (-l). Set these options in +`/etc/init.d/puppetmaster` using variable `PUPPETMASTER_OPTS`:: + + # vi /etc/init.d/puppetmaster + ... + PUPPETMASTER_OPTS="-v -d -l /var/log/puppet/puppetmaster.log" + ... + + # /etc/init.d/puppetmaster restart + + +On the Puppet Client Side +~~~~~~~~~~~~~~~~~~~~~~~~~ + +To specify which environment the Puppet client uses you can specify a +value for the environment configuration variable in the client's +`puppet.conf` file. Here the environment `developmentSL53` is set. + +Additionally the name of the puppet server `psi-puppet1.psi.ch` is +assigned:: + + # vi /etc/puppet/puppet.conf + [main] + vardir = /var/puppet + logdir = /var/log/puppet + rundir = /var/run/puppet + ssldir = $vardir/ssl + environment = developmentSL53 + + [puppetd] + classfile = $vardir/classes.txt + localconfig = $vardir/localconfig + factsync = true + server = psi-puppet1.psi.ch + +In the Kickstart +~~~~~~~~~~~~~~~~ + +In the SL 5.3 Installation Tree +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create the base directories, its subdirectories and some first test +file for the `Basic` class as declared above in the manifest +`basic.pp` on the server:: + + # cd /afs/psi.ch/software/linux/dist/scientific/53/ + # mkdir -p puppet/files/Basic/etc + # touch puppet/files/Basic/etc/puppet-test-file diff --git a/admin-guide/legacy/misc/puppetmasteratpsi.rst b/admin-guide/legacy/misc/puppetmasteratpsi.rst new file mode 100644 index 00000000..ca6c7d9b --- /dev/null +++ b/admin-guide/legacy/misc/puppetmasteratpsi.rst @@ -0,0 +1,76 @@ +Puppetmaster At PSI +=================== + +Procedure +--------- + +Manual Check Whether Puppetmaster Is Running +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Contemporary, the `puppetmasterd` process often crashes and automatic +restart fails. Thus it has to be started manually again. Therefore login +to `pxeserv01`, check whether the process is still running and if not, +restart `puppetmasterd`. + +Check whether the `puppetmasterd` is running:: + + [root@pxeserv01 ~]# ps ax | grep puppet + 549 pts/0 S+ 0:00 grep puppet + 6641 ? S 7:53 /bin/bash ./test-and-restart-puppetmaster.sh + +It's not running. + +Check the logfile. The logfile is situated on AFS:: + + # tail /afs/psi.ch/service/linux/puppet/var/log/puppetmaster.log + ... + Mon Jan 26 09:22:27 +0100 2009 Puppet (notice): Compiled configuration for slsnedi1.psi.ch in 0.09 seconds + Mon Jan 26 09:24:55 +0100 2009 Puppet (notice): Caught TERM; shutting down + Mon Jan 26 09:24:55 +0100 2009 Puppet (notice): Shutting down + Mon Jan 26 09:24:55 +0100 2009 Puppet (err): Could not remove PID file /var/run/puppet/puppetmasterd.pid + Mon Jan 26 09:25:01 +0100 2009 Puppet (err): Could not create PID file: /var/run/puppet/puppetmasterd.pid + + +In this case remove `/var/run/puppet/puppetmasterd.pid` and restart the server:: + + # rm /var/run/puppet/puppetmasterd.pid + # /etc/init.d/puppetmaster restart + + +Check again whether the `puppetmasterd` is running:: + + # [root@pxeserv01 ~]# ps ax | grep puppet + 549 pts/0 S+ 0:00 grep puppet + 6641 ? S 7:53 /bin/bash ./test-and-restart-puppetmaster.sh + 31599 ? Ssl 0:03 /usr/bin/ruby /usr/sbin/puppetmasterd \ + --logdest=/afs/psi.ch/service/linux/puppet/var/log/puppetmaster.log + + +Finally, test it on a client:: + + # [root@pc7377 ~]# psi-puppet + ... + puppetd was running successfully + + +Automatic Check Whether Puppetmaster Is Running +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +On `pxeserv01` the script `/root/test-and-restart-puppetmaster.sh` +continuously observes the `puppetmasterd` and should restart it when +it's hanging. + +The script is started in the following way:: + + # [root@pxeserv01 etc]# nohup /root/test-and-restart-puppetmaster.sh & + + +The output is written to: + +- `$HOME/nohup.out` + + The logfile. + +- `/dev/shm/puppetwatch.1` + +- `/dev/shm/puppetwatch.2` diff --git a/admin-guide/legacy/misc/release_snapshotssl53.rst b/admin-guide/legacy/misc/release_snapshotssl53.rst new file mode 100644 index 00000000..5e6bbc2c --- /dev/null +++ b/admin-guide/legacy/misc/release_snapshotssl53.rst @@ -0,0 +1,188 @@ +Update SL53 i386 and x86_64 +=========================== + +Get Native Scientific Linux Updates +----------------------------------- + +This section describes how the particular linux repositories are +updated by looking for new RPMS in our mirror and copying them from +there to the repositories. + + +Get the Latest Security Update RPMS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the latest security update RPMS from the local SL53 mirror for +both architectures, i386 and x86_64, by invoking +`update_repo_all_directories.sh` on tux50. They will be copied to the +corresponding `.../update.${ARCH}/all/` directories. This will take +some time:: + + # cd /afs/psi.ch/software/linux/dist/scientific/53/scripts/ + # ./update_repo_all_directories.sh > ~/tmp/20090930-update_repo_all_directories.sl53.output 2>&1 + +Then, check for errors in the log file:: + + # grep -i error ~/tmp/20090930-update_repo_all_directories.sl53.output + ... + +Finally, run `update_symlinks_in_rpms_all.sh` to keep all symlinks in +the directory +`/afs/psi.ch/software/linux/dist/scientific/53/RPMS_all/` up to date. + +The script removes dead links and creates new links to the new RPMS. +It is basically not necessary for running PSI updates, rather it's +just convenient to have a directory with the list of all RPMS of a +distribution:: + + # ./update_symlinks_in_rpms_all.sh + + +Create A New PSI Version And Release The SLP Snapshots +------------------------------------------------------ + +Keep the following order: + +- Update the "all" repositories. (Described in section texttext) + +- Create new snapshots. (Described in section texttext) + +- Release "unstable" from new snapshots. + +- Create a new PSI version. + +- Release "testing". + +- Release "stable". + + +Release Unstable +~~~~~~~~~~~~~~~~ + +The "unstable" distribution is where active development of SLP occurs. +Generally, this distribution is run by developers and those who like +to live on the edge. + +The command `release_unstable.sh` will update the respective symlinks +`.../unstable` to the latest snapshots. + +Because `release_unstable.sh` is interactive, you should not redirect +the output to a file, as you won't be able to see the questions asked. + +Before `release_unstable.sh`:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/53/ + # ls -l */unstable + + # ./release_unstable.sh + +After `release_unstable.sh`:: + + # ls -l */unstable + +As soon as an unstable distribution has become testing a new unstable +can be generated that again points to the new latest snapshots. + + +Create A New PSI Version +~~~~~~~~~~~~~~~~~~~~~~~~ + +As soon as the new PSI version is created, i.e. the symbolic links +which point to the same target snapshots as the latest unstable +snapshots, the PSI auto-update process is active again for the hosts +which are set to unstable:: + + # cd /afs/psi.ch/software/linux/dist/scientific/53/scripts + # ./create_new_psi_version.sh + + +Release Testing +~~~~~~~~~~~~~~~ + +The "testing" distribution contains packages that haven't been +accepted into a "stable" release yet, but they are in the queue for +that. The main advantage of using this distribution is that it has +more recent versions of software. + +The command `release_testing.sh` will update the respective symlinks +`.../testing` to the latest unstable snapshots. + +Because `release_testing.sh` is interactive, you should not redirect +the output to a file, as you won't be able to see the questions asked. + +Before `release_testing.sh`:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/53/ + # ls -l */testing + + # ./release_testing.sh + +After `release_testing.sh`:: + + # ls -l */testing + + +Release Stable +~~~~~~~~~~~~~~ + +The "stable" distribution, formerly known as "current", contains the +latest officially released distribution of SLP. + +This is the production release of SLP, the one which we primarily +recommend using. + +The command `release_stable.sh` will update the respective symlinks +`.../stable` to the latest unstable snapshots. + +Because `release_stable.sh` is interactive, you should not redirect +the output to a file, as you won't be able to see the questions asked. + +Before `release_stable.sh`:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/53/ + # ls -l */stable + + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:25 cluster/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:23 enhanced/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 18 Sep 18 11:24 kernel/stable -> 2.6.18-128.1.1.el5 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:24 nonfree/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:22 others/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:21 psi/stable -> 20090821 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:22 update.i386/stable -> 20090820 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:21 update.x86_64/stable -> 20090820 + + # ./release_stable.sh + + ### begin ./release_stable.sh ### + Sourcing configuration file ./dist-config + + TOP_DIR is /afs/psi.ch/software/linux/dist/scientific/53 + + Running ./release_stable.sh ... + + Latest snapshot in psi: + /afs/psi.ch/software/linux/dist/scientific/53/psi/testing -> 20090916 + Latest snapshot in others: + /afs/psi.ch/software/linux/dist/scientific/53/others/testing -> 20090916 + Latest snapshot in update.i386: + /afs/psi.ch/software/linux/dist/scientific/53/update.i386/testing -> 20090916 + Latest snapshot in update.x86_64: + /afs/psi.ch/software/linux/dist/scientific/53/update.x86_64/testing -> 20090916 + Latest snapshot in enhanced: + /afs/psi.ch/software/linux/dist/scientific/53/enhanced/testing -> 20090916 + Latest snapshot in kernel: + /afs/psi.ch/software/linux/dist/scientific/53/kernel/testing -> 2.6.18-128.7.1.el5 + Latest snapshot in nonfree: + /afs/psi.ch/software/linux/dist/scientific/53/nonfree/testing -> 20090916 + Latest snapshot in cluster: + /afs/psi.ch/software/linux/dist/scientific/53/cluster/testing -> 20090916 + + Relink stable to the latest snapshots (y/n)? + + +After `release_stable.sh`:: + + # ls -l */stable diff --git a/admin-guide/legacy/misc/repairrpmdb.rst b/admin-guide/legacy/misc/repairrpmdb.rst new file mode 100644 index 00000000..f9cbe9fd --- /dev/null +++ b/admin-guide/legacy/misc/repairrpmdb.rst @@ -0,0 +1,21 @@ +Repair the RPM DB +================= + +Introduction +------------ + +Sometimes the rpm database gets broken and any command of manipulating +or questioning RPMS might fail. + +So, it can be necessary to remove the corrupted RPM database and to +reinitialize it. + +Procedure +--------- + +Run:: + + # cd /var/lib/rpm + # rm -f __db.* + # rpmdb --initdb + # rpmdb --rebuilddb diff --git a/admin-guide/legacy/misc/sap_client_for_linux_howto.rst b/admin-guide/legacy/misc/sap_client_for_linux_howto.rst new file mode 100644 index 00000000..eecc1159 --- /dev/null +++ b/admin-guide/legacy/misc/sap_client_for_linux_howto.rst @@ -0,0 +1,120 @@ +Installation of SAP Citrix Client and Prerequisites +=================================================== + +SL6 32 bit +---------- + +First tests with rebuild of SRPMS of pcsc-lite and pcsc-lite-libs +version 1.5.2-7 without hal support. + +Install pcsl-lite 1.5.2 (SmartCard daemon) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run:: + + # yum install pcsc-lite + # yum install pcsc-lite-libs + + +Install Omnikey SmartCard driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run:: + + # yum --enablerepo beta install omnikey-usb-3121-driver # todo: move the driver to the stable repo + # /etc/init.d/pcscd restart + +or for debug mode:: + + # /usr/sbin/pcscd -df + + +Install Citrix ICA Client +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run:: + + # yum install openmotif libXp + # yum install ICAClient + + +SL6 64 bit +---------- + +Install pcsc-lite-1.5.3 +~~~~~~~~~~~~~~~~~~~~~~~ + +The following packages have to be present/installed. + + - alsa-lib, alsa-lib.i686, gtk2-devel, gtk2-devel.i386, glibc, glibc.i686, glibc-devel, glibc-devel.i686 + - libgcc, libgcc.i686, libusb, libusb.i686, libusb-devel, libusb-devel.i686 + - libXpm, libXpm.i686, libXaw, libXaw.i686, nspluginwrapper, nspluginwrapper.i686 + - openmotif, openmotif.i686, openmotif-devel, openmotif-devel.i686 + - libusb1, libusb1.i686, libusb1-devel, libusb1-devel.i686 + +Remove the preinstalled pcsc-lite packages:: + + # rpm -e --nodeps pcsc-lite pcsc-lite-libs pcsc-lite-openct + + +Download, unpack pcsc-lite-1.5.3 sources, run configure and build the +daemon:: + + # wget --no-check-certificate https://alioth.debian.org/frs/download.php/3017/pcsc-lite-1.5.3.tar.bz2 + # tar xvf pcsc-lite-1.5.3.tar + # cd pcsc-lite-1.5.3.tar + + # ./configure --enable-usbdropdir=/usr/lib/pcsc/drivers --disable-libhal --prefix=/usr CFLAGS=-m32 CXXFLAGS=-m32 LDFLAGS=-m32 + + # make + # make check + # make install + + +Install Omnikey SmartCard driver +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run:: + + # yum --enablerepo beta install omnikey-usb-3121-driver # todo: move the driver to the stable repo + #todo: dependency pcsc-lite-libs??? + # /etc/init.d/pcscd restart + +or for debug mode:: + + # /usr/sbin/pcscd -df + + +Install Citrix ICA Client +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run:: + + # yum install openmotif libXp + # yum install ICAClient + + +Start SAP Session +----------------- + +Plug in the Omnikey 3121 USB SmartCard reader, and plug in the +SmartCard. + +Start the Citrix Receiver (E.g. in KDE: Applications --> Internet --> +Citrix Receiver) and login to the terminal server tsadlm01, use your +Windows login and password. + +Then run the APPGATE_Start application by clicking the icon. + +Open the connection to the server acc1.caz.admin.ch using the method +certificate and keep the autoselected certificate, read from the +SmartCard reader. Click ok. + +Enter your password for the SmartCard token and click ok. + +Internet Explorer starts and pops up to websites, HP something and one +from the BIT. Close them or leave them, as you like. + +Switch to the cmd.exe console of the terminal server and press any +key. UltraLogon will start and open the SAP main window, where you +select your session. diff --git a/admin-guide/legacy/misc/updatesl57.rst b/admin-guide/legacy/misc/updatesl57.rst new file mode 100644 index 00000000..f7357cdc --- /dev/null +++ b/admin-guide/legacy/misc/updatesl57.rst @@ -0,0 +1,282 @@ +Update SL57 and later i386 and x86_64 +===================================== + +Introduction +------------ + +Keep the following order: + +- Get the latest security updates from the SL mirror for the + "update.$ARCH" repository. + +- Build kernel modules. + +- Get updates for the "psi" repository. + +- Get updates for the "other" repository. + +- Get updates for the "nonfree" repository. + +- Create new snapshots. + +- Release "unstable" from new snapshots. + +- Create a new PSI version. + +- Release "testing". + +- Release "stable". + + +Update The Different Repositories +--------------------------------- + +Get the Latest Security Update RPMS From SL Mirror +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get the latest security update RPMS from the local SL57 mirror for +both architectures, i386 and x86_64, by invoking +`rsync_security_updates_to_all_directories.sh` on tux50. + +They will be copied to the corresponding `.../updates.${ARCH}/all/` +directories. This will take some time:: + + # cd /afs/psi.ch/software/linux/dist/scientific/57/scripts/ + # nohup ./rsync_security_updates_to_all_directories.sh > \ + # UPDATE_LOG/$(date +%Y-%m-%d)-rsync_security_updates_to_all_directories.log 2>&1 & + +Then, check for errors in the log file:: + + # grep -i error UPDATE_LOG/20091221-rsync_security_updates_to_all_directories.log + ... + +Finally, run `update_symlinks_in_rpms_all.sh` to keep all symlinks in +the directory +`/afs/psi.ch/software/linux/dist/scientific/57/RPMS_all/` up to date. + +The script removes dead links and creates new links to the new RPMS. +It is basically not necessary for running PSI updates, rather it's +just convenient to have a directory with the list of all RPMS of a +distribution:: + + # ./update_symlinks_in_RPMS_all.sh + +Build Kernel Modules +~~~~~~~~~~~~~~~~~~~~ + +First install the latest kernel and kernel-devel packages on the +respective build systems. + +Then build the RPMS on the corresponding build systems using the +scripts below. + +32 bit:: + + # [gasser_m@tukan50-32] + # cd /afs/psi.ch/software/linux/dist/scientific/57/scripts + # sh build_kernel_modules.sh 2.6.18-194.3.1.el5 > \ + # UPDATE_LOG/20100630-build_kernel_modules-2.6.18-194.3.1.el5.i686.log 2>&1 + + # check-set-of-built-kernel-modules.bash /tmp/rpms_for_2.6.18-194.3.1.el5 \ + # KERNEL_MODULES_TO_BUILD/sl5.i386.kms-to-be-built + + # sh build-gpfs.sl5x.i386.sh + + +64 bit:: + + # [gasser_m@tux50-64] + # cd /afs/psi.ch/software/linux/dist/scientific/57/scripts + # sh build_kernel_modules.sh 2.6.18-194.3.1.el5 > \ + # UPDATE_LOG/20100630-build_kernel_modules-2.6.18-194.3.1.el5.x86_64.log 2>&1 + + # check-set-of-built-kernel-modules.bash /tmp/rpms_for_2.6.18-194.3.1.el5 \ + # KERNEL_MODULES_TO_BUILD/sl5.x86_64.kms-to-be-built + + # sh build-gpfs.sl5x.x86_64.sh + + +Finally, from both build systems, copy the built kernel modules to the +psi repository:: + + # cp -av `cat /tmp/rpms_for_2.6.18-194.3.1.el5` /afs/psi.ch/software/linux/dist/scientific/57/psi/all/ + + +Get Updates For The Psi Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Get Updates For The Other Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + +Get Updates For The Nonfree Repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create New Snapshots +-------------------- + +The script `create_new_snapshots.sh` will pick out the latest version +of each RPM found in the active repositories. + +It will create a subdirectory (snapshot) in each repository and name +it after the current date using the format YYYYMMDD. + +Then it will place a symbolic link into this subdirectory for each +latest RPM found in the `all` subdirectory of the currently processed +repository. + +To invoke it run the following command:: + + # nohup ./create_new_snapshots.sh alldirs > UPDATE_LOG/$(date +%Y-%m-%d)-create_new_snapshots.log 2>&1 & + + +Release Unstable, Create A New PSI Version And Release The Other SLP Snapshots +------------------------------------------------------------------------------ + +Release Unstable +~~~~~~~~~~~~~~~~ + +The "unstable" distribution is where active development of SLP occurs. +Generally, this distribution is run by developers and those who like +to live on the edge. + +The command `release_unstable.sh` will update the respective symlinks +`.../unstable` to the latest snapshots. + +Because `release_unstable.sh` is interactive, you should not redirect +the output to a file, as you won't be able to see the questions asked. + +Before `release_unstable.sh`:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/57/ + # ls -l */unstable + + # ./release_unstable.sh + + +After `release_unstable.sh`:: + + # ls -l */unstable + + +As soon as an unstable distribution has become testing a new unstable +can be generated which again points to the new latest snapshots. + + +Create A New PSI Version +~~~~~~~~~~~~~~~~~~~~~~~~ + +Run:: + + # cd /afs/psi.ch/software/linux/dist/scientific/57/scripts + # sh create_new_psi_version.sh + +As soon as the new PSI version is created, i.e. the symbolic links +which point to the same target snapshots as the latest unstable +snapshots, the psi-version-info.txt file has to be actualized to +activate the PSI auto-update again for the hosts which are set to +unstable:: + + # ./create_file_psiversion-info.sh + +Eventually, test the unstable release. + + +Release Testing +~~~~~~~~~~~~~~~ + +The "testing" distribution contains packages that haven't been +accepted into a "stable" release yet, but they are in the queue for +that. The main advantage of using this distribution is that it has +more recent versions of software. + +The command `release_testing.sh` will update the respective symlinks +`.../testing` to the latest unstable snapshots. + +If the puppet environment DesktopSL5Unstable was modified and the +changes should be made in DesktopSL5Testing, too, run +`rsync_puppet_env_testing_with_unstable.sh` before +`release_testing.sh`. + +Because `release_testing.sh` is interactive, you should not redirect +the output to a file, as you won't be able to see the questions asked:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/57/scripts + + # ./rsync_puppet_env_testing_with_unstable.sh + # ./rsync_kickstart_dir_DesktopTesting_with_DesktopUnstable.sh + # ./release_testing.sh + + # ./create_file_psiversion-info.sh + + +Release Stable +~~~~~~~~~~~~~~ + +To activate the PSI auto-update again for testing hosts the +psi-version-info.txt file has to be actualized. + +The "stable" distribution, formerly known as "current", contains the +latest officially released distribution of SLP. + +This is the production release of SLP, the one which we primarily +recommend using. + +The command `release_stable.sh` will update the respective symlinks +`.../stable` to the latest unstable snapshots. + +The procedure is analogous to the procedure described in the "Release +Testing" section:: + + # ./rsync_puppet_env_stable_with_testing.sh + # ./rsync_kickstart_dir_DesktopStable_with_DesktopTesting.sh + # ./release_stable.sh + # ./create_file_psiversion-info.sh + + + ### begin ./release_stable.sh ### + Sourcing configuration file ./dist-config + + TOP_DIR is /afs/psi.ch/software/linux/dist/scientific/57 + + Running ./release_stable.sh ... + + Latest snapshot in psi: + /afs/psi.ch/software/linux/dist/scientific/57/psi/testing -> 20090916 + Latest snapshot in others: + /afs/psi.ch/software/linux/dist/scientific/57/others/testing -> 20090916 + Latest snapshot in update.i386: + /afs/psi.ch/software/linux/dist/scientific/57/update.i386/testing -> 20090916 + Latest snapshot in update.x86_64: + /afs/psi.ch/software/linux/dist/scientific/57/update.x86_64/testing -> 20090916 + Latest snapshot in kernel: + /afs/psi.ch/software/linux/dist/scientific/57/kernel/testing -> 2.6.18-128.7.1.el5 + Latest snapshot in nonfree: + /afs/psi.ch/software/linux/dist/scientific/57/nonfree/testing -> 20090916 + Latest snapshot in cluster: + /afs/psi.ch/software/linux/dist/scientific/57/cluster/testing -> 20090916 + + Relink stable to the latest snapshots (y/n)? + + +Before `release_stable.sh`:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/57/ + # ls -l */stable + + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:25 cluster/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:23 enhanced/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 18 Sep 18 11:24 kernel/stable -> 2.6.18-128.1.1.el5 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:24 nonfree/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:22 others/stable -> 20090316 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:21 psi/stable -> 20090821 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:22 update.i386/stable -> 20090820 + lrwxr-xr-x 1 gasser_m ait 8 Sep 18 11:21 update.x86_64/stable -> 20090820 + + +After `release_stable.sh`:: + + # ls -l */stable diff --git a/admin-guide/legacy/misc/updateslmaindoc.rst b/admin-guide/legacy/misc/updateslmaindoc.rst new file mode 100644 index 00000000..cec90864 --- /dev/null +++ b/admin-guide/legacy/misc/updateslmaindoc.rst @@ -0,0 +1,1275 @@ +Updates for SL 4 and SL 5.1 +=========================== + +References +---------- + +- https://wiki.intranet.psi.ch/AIT/LinuxRegularUpdate (U. Beyerle) + +- https://wiki.intranet.psi.ch/AIT/SL5RegularUpdates200807 (V. Markushin) + + +Introduction +------------ + +The following text describes how regular Scientific Linux (SL) updates +for SL51 and SL4, are performed. + +A detailed standard procedure is exemplified for an SL 51 update on a +64 bit machine, but the same operation is followed for other SL +releases <= SL51 and architectures. Deviations from the standard +procedure are emphasized in the text. + + +General Remarks +~~~~~~~~~~~~~~~ + +Regular Linux Udpates are scheduled every first Wednesday in a month. + +Create a new Testing Release one week in advance. + +It is advised to create the new version for a release on the +respective build system. For example for SL5 i386 do it on tux50 with +your AFS account, for AFS ACLs see "Required File Permissions On AFS" +below. + +When you compile new kernel module RPMS then it's recommended to use +build systems. + + +Reasons For Using Build Systems +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- Performance: Some scripts will just horribly slow down your desktop + machine, making it almost impossible to work on it while the + respective script is running. So, using a build system will not + affect the performance of your desktop computer. + +- Version conflicts: Some versions of some tools such as yum, + createrepo, etc., might be different in different SL releases, thus + to avoid conflicts one should use the version of the tool that comes + with the corresponding release. Other packages might be missing at + all, e.g. some devel packages used when RPMS are built or tool like + createrepo, which are not required on a default Desktop. + +- Compiling software: For compiling software, e.g. building kernels, + kernel modules, etc., it first has to be on the right architecture, + and second it's also recommended to do it in some clean default + environment, which is a representative for the environments of + productive systems. + + +Scientific Linux Mirror at PSI +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +RPMS are taken from our mirror at +`/afs/psi.ch/software/mirror/scientific/`. The mirror is updated +daily by a cronjob running on pxeserv01. (See also +LinuxInstallationServer.):: + + # file pxeserv01:/etc/cron.d/mirror + + # Mirroring of rpm repositories at 07:00 + # + 00 07 * * * root /afs/psi.ch/software/mirror/scripts/mirror.sh > /dev/null 2>&1 + +The script `/afs/psi.ch/software/mirror/scripts/mirror.sh` reads +`/afs/psi.ch/software/mirror/scripts/mirror.conf` to know about +locations of ftp external software repositories and where to place the +files on our local mirror. + +E.g.: The archive +`ftp://ftp.scientificlinux.org/linux/scientific/46/i386` is locally +mirrored at `/afs/psi.ch/software/mirror/scientificlinux/46/i386`. + + +Autoupdate in SL5 +~~~~~~~~~~~~~~~~~ + +The script `/usr/sbin/psi-auto-update` is started via cron usually in +the night and triggers the update, the latter is performed by scripts +and Puppet. The update is released the first Wednesday of a +month. Default Desktop computers will be updated during the night from +Wednesday to Thursday. + + +Preparatory Work +---------------- + +Required File Permissions On AFS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Before starting with performing updates, you need the corresponding +permissions to do things in the PSI linux repository directory at +`/afs/psi.ch/software/linux/dist/scientific/`, which is on an AFS +volume. + +Check permissions using AFS commands and get the required AFS access. +The unix commands `ls -l` etc. will work but not show you the relevant +AFS permissions, instead use the AFS command `fs`. + +E.g.: Type `fs help` to see a list of command attributes:: + + # fs listacl /afs/psi.ch/software/linux/ + ... + or + + # fs listacl /afs/psi.ch/software/mirror/ + Access list for /afs/psi.ch/software/mirror is + Normal rights: + ait:sw_adm rlidwka + psi:nodes rl + system:authuser rl + +To work in the linux distribution directories you need to be in the +following AFS groups (output of `pts mem AFS_USERNAME`):: + + # pts mem gasser_m + Groups gasser_m (id: 2374) is a member of: + ait:sw_adm + linux:users + ait:users + + +Prepare Your Build Environment For Building RPMS +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For building RPMS you have two possibilities: + +- build locally in your build directories + +- build on AFS in common build directories + + +Build locally +............. + +Before you start building RPMS you create the following directories on +each build system. + +Example for tux50-64:: + + # ssh gasser_m@tux50-64 + # mkdir /scratch/gasser_m + # cd /scratch/gasser_m + # mkdir rpm_tmp rpm_topdir + # cd rpm_topdir + # mkdir BUILD RPMS SOURCES SPECS SRPMS + + +Your build environment is set in "~/.rpmmacros":: + + %WORKDIR %(echo "/scratch/$USER") + %_topdir /scratch/gasser_m/rpm_topdir + %_tmppath /scratch/gasser_m/rpm_tmp + %packager Marc Gasser + %vendor PSI Scientific Linux + %sl_site slp + %sl_site_version %(rpm -q --qf "%{v}" sl-release | cut -d"." -f1) + %os_release %{sl_site}%{sl_site_version} + %dist .%{os_release} + %rhel %sl_site_version + %debug_package %{nil} + + +The command `rpmbuild` is used to build RPMS. The built RPMS are +found in the RPMS directory of your build environment on your build +system. + + +Build on AFS +............ + +Change to `/afs/psi.ch/project/linux/src/scientific/RPMS`. There you +will find separate subdirectories, each for one specific RPM. + +Check that your `.rpmmacros` does not mess up the build environment +for this kind of building. Change to the subdirectory of the RPM you +want to build and use the script `psi-rpmbuild`, which sets up the +build environment (thus `.rpmmacros` is not required at all). In the +subdirectory run `psi-rpmbuild -bb` for building a binary package only +for instance. + +E.g.: To build the psi-desktop package version 2.x do the following on +a build system:: + + # cd psi-desktop-2/ + # psi-rpmbuild -bb + + +The built RPM can be found in the corresponding subdirectory in +`/afs/psi.ch/project/linux/dist/`. + +The big advantages of this procedure are, you don't have to install +the sources on each build system, instead you install them once in +AFS, and this centralized build environment can be shared among +different users on different hosts. + + +Check Diskspace +~~~~~~~~~~~~~~~ + +Before starting the update check the diskspace left on your file +systems involved. + +- For copying new RPMS from the mirror to the repositories + +To be on the safe side there should be 1 G of free diskspace on the +respctive AFS volumes, where RPMS are copied to:: + + [gasser_m@pc7377 tmp]$ fs lq /afs/psi.ch/software/linux/dist/scientific/305/ + Volume Name Quota Used %Used Partition + sw.dist.sl305 25000000 23317560 93%<< 88% < + + 728d4109f520336bb6b5f595de9dd2db acroread-8.1.6-2.el5.i386.rpm + fd1b8fb934140222460ed81c34420d90 acroread-plugin-8.1.6-2.el5.i386.rpm + + # md5sum -c file.md5sum + + +Kernel Update SL5 +----------------- + +This section describes the kernel update for SL51, 32 and 64 bit. + +The SL5 kernel update procedure described here is basically the same +for SL4. However, a lot of details such as names of files, kernel +modules, build systems, etc., differ, thus the whole SL4 procedure is +shown in its own section, too. See `Kernel Update SL4`. + +The general remarks below are valid for SL4, too. + + +General Remarks Referring To Kernel Update +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a new SL kernel is released also a lot of corresponding kernel +module packages are coming with this kernel to extend its +functionality, e.g. kernel-module-xfs to facilitate Xfs support of the +kernel. + +Now, in case a new kernel has been released you have to build a set of +kernel-module RPMS, which at PSI are provided in addition to those +coming with the regular SL updates. + +It's recommended to use dedicated build systems to build RPMS. + +To compile kernel modules some prerequisites have to be met. + +- A build environment has to be set up on your build system + (e.g. tux50-64 for SL5 x86_64), locally or on AFS as discussed + before. + +- New kernel and kernel-devel RPMS have to be installed on your build + system. + +- The particular kernel module source RPMS have to be installed on + your build system. + +- About 1 G of free diskspace. + +- Note: For compiling new kernel modules the corresponding kernel has + to be installed on your build system but must not be running and you + can build the modules in a non-root environment. + + +Kernel Update SL5 32-bit +........................ + +Follow the procedure shown in the 64-bit section below. Differences +between building of the 32 and 64 bit kernel modules are pointed out. + +The main difference is, first, that you have to build kernel, +kernel-xen and kernel-PAE modules for 32 bit systems, while you build +only kernel and kernel-xen modules for 64 bit. The GPFS kernel module +is build for both, 32 and 64 bit systems. + + +Kernel Update SL5 64-bit +........................ + +(Example for PSI update SL5 version 31, June 2009.) + +Login to your build system and check which kernel packages are already +installed:: + + # [gasser_m@tux50-64 ~]$ rpm -q kernel{,-xen,-devel,-xen-devel} + + kernel-2.6.18-92.1.22.el5 + kernel-2.6.18-128.1.1.el5 + kernel-2.6.18-128.1.6.el5 + kernel-xen-2.6.18-92.1.22.el5 + kernel-xen-2.6.18-128.1.1.el5 + kernel-xen-2.6.18-128.1.6.el5 + kernel-devel-2.6.18-92.1.22.el5 + kernel-devel-2.6.18-128.1.1.el5 + kernel-devel-2.6.18-128.1.6.el5 + kernel-xen-devel-2.6.18-92.1.22.el5 + kernel-xen-devel-2.6.18-128.1.1.el5 + kernel-xen-devel-2.6.18-128.1.6.el5 + + +Check whether there is a newer kernel package in the repository:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/update.x86_64/all/ + # ls -1 kernel*-2.* | grep -v module | get-latest-RPM-from-RPM-list.pl - + ... + kernel-2.6.18-128.1.14.el5 + +Latest version of installed kernels is `2.6.18-128.1.6.el5` , latest +version in the repository is `2.6.18-128.1.14.el5`, i.e. new SLP +kernel modules have to be built. + +Check the diskspace of your build partition, 1G is ok:: + + # [gasser_m@tux50-64 all]$ df -hT /scratch + Filesystem Type Size Used Avail Use% Mounted on + /dev/mapper/VolGroup00-LogVol00 + ext3 14G 12G 1.6G 89% / + + +Is there a listing of all kernel module packages to be built? + + +Installation Of Kernel And Kernel-devel RPMS On 64 Bit SL5 Build System +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Install new kernel and kernel-devel RPMS as root on tux50-64. + +RPMS for the following kernels are required: kernel, kernel-xen:: + + # [root@tux50-64] + # cd /afs/psi.ch/software/linux/dist/scientific/51/update.x86_64/all/ + # ls -1 kernel-{,devel-,xen-,xen-devel-}2.6.18-128.1.14.el5.x86_64.rpm + kernel-2.6.18-128.1.14.el5.x86_64.rpm + kernel-devel-2.6.18-128.1.14.el5.x86_64.rpm + kernel-xen-2.6.18-128.1.14.el5.x86_64.rpm + kernel-xen-devel-2.6.18-128.1.14.el5.x86_64.rpm + + # rpm -ivh kernel-{,devel-,xen-,xen-devel-}2.6.18-128.1.14.el5.x86_64.rpm + + warning: kernel-2.6.18-128.1.14.el5.x86_64.rpm: Header V3 DSA signature: NOKEY, key ID 82fd17b2 + Preparing... ########################################### [100%] + 1:kernel-xen-devel ########################################### [ 25%] + 2:kernel ########################################### [ 50%] + 3:kernel-devel ########################################### [ 75%] + 4:kernel-xen warning: /etc/modprobe.d/blacklist-firewire created as /etc/modprobe.d/blacklist-firewire.rpmnew + ########################################### [100%] + + +Installation Of Kernel And Kernel-devel RPMS On 32 Bit SL5 Build System +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Again, login as root to your build system to install the kernel +packages. + +For the 32 bit system also the PAE kernel modules are required:: + + # [root@tukan50-32] + # cd /afs/psi.ch/software/linux/dist/scientific/51/update.i386/all/ + # ls -1 kernel-{,devel-,PAE-,PAE-devel-,xen-,xen-devel-}2.6.18-128.1.14.el5.i686.rpm + # rpm -ivh kernel-{,devel-,PAE-,PAE-devel-,xen-,xen-devel-}2.6.18-128.1.14.el5.i686.rpm + + +Installation Of SL5 Kernel Module SRPMS On Build Systems +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Do this on both, the 32 and 64 bit build system. + +To build the kernel module RPMS the corresponding SRPMS have to be +installed on your build system first. + +List of SL5 kernel-module RPMS to be built for i686 and x86_64:: + + Name (without kernel version) Release Remarks + kernel-module-airprime 2.6.18-1.slp5 + kernel-module-atl2 1.0.40.2-1.slp5 + kernel-module-aufs 0.20070210.cvs-4.slp5 + kernel-module-firewire 2.6.18-2.slp5 + kernel-module-gspcav1 01.00.20-1.slp5 + kernel-module-iwlwifi 1.2.25-1.slp5 currently not builded + kernel-module-ntfs 2.1.27-0.rr.10.0 currently not builded + kernel-module-openafs 1.4.6-73.slp5 no SRPM, build script provided by A. Gsell + kernel-module-qla2xxx 8.01.07.15-1.slp5 + kernel-module-uvcvideo 0.1.0-1.svn148.slp5 + kernel-module-VMwareTools 6530-29999.slp5 no SRPM, build script provided by A. Gsell + kernel-module-gpfs texttext 64 bit only, no SRPM, build script provided by H.C. Stadler + + +Copy the PSI relevant source RPMS (SRPMS) to your build environment, +except sources of kernel modules ntfs, openafs, gpfs and +VMwareTools. They are built in their own environments. + +The SRPMS of the following 7 modules are required:: + + aufs firewire gspcav1 uvcvideo qla2xxx atl2 airprime + (see variable specfiles in /afs/psi.ch/software/linux/dist/scientific/51/scripts/build_kernel_modules.) + + +They can be found in the directory:: + + /afs/psi.ch/software/linux/dist/scientific/51/psi/all/ + + +Check for latest versions of required SRPMS:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/psi/all/ + # ll {aufs,firewire,gspcav1,uvcvideo,qla2xxx,atl2,airprime}*.src.rpm + + -rw-r--r-- 1 beyerle ait 7566 Apr 24 22:39 airprime-2.6.18-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 56446 Apr 8 11:43 atl2-1.0.40.2-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 77012 Apr 8 21:03 atl2-1.0.40.4-4.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 136658 Oct 1 2007 aufs-0.20070210.cvs-4.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 427554 Jul 16 10:48 aufs-0.20080605.cvs-5.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 295158 Aug 21 2007 firewire-2.6.18-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 295120 Jan 22 2008 firewire-2.6.18-2.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 217470 May 15 10:36 gspcav1-01.00.20-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 195078 Nov 12 2007 gspcav1-1.00.18-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 2015550 Mar 10 22:04 qla2xxx-8.01.07.15-1.slp5.src.rpm + -rw-r--r-- 1 beyerle ait 91123 Dec 7 2007 uvcvideo-0.1.0-1.svn148.slp5.src.rpm + + +The following versions were taken as the latest: (This list can be +found in the file +`tux50-64:/scratch/gasser_m/rpm_topdir/SRPMS/20090624-psi-src-rpms.list`.):: + + airprime-2.6.18-1.slp5.src.rpm + atl2-1.0.40.4-4.slp5.src.rpm + #aufs-0.20080605.cvs-5.slp5.src.rpm # kernel-module-aufs is in SL51update and SL54base now + firewire-2.6.18-2.slp5.src.rpm + gspcav1-01.00.20-1.slp5.src.rpm + qla2xxx-8.01.07.15-1.slp5.src.rpm + uvcvideo-0.1.0-1.svn148.slp5.src.rpm + + +For convenience copy them first to your $rpm_topdir/SRPMS/ and then +unpack them, if not yet done (being still gasser_m@tux50-64):: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/psi/all + # for i in `cat /scratch/gasser_m/rpm_topdir/SRPMS/20090624-psi-src-rpms.list` + # do + # cp $i /scratch/gasser_m/rpm_topdir/SRPMS/ + # done + + +Then install them into your build environment:: + + # cd /scratch/gasser_m/rpm_topdir/SRPMS/ + # rpm -ivh `cat 20090624-psi-src-rpms.list` + + 1:airprime ########################################### [100%] + 2:atl2 ########################################### [100%] + 3:aufs ########################################### [100%] + 4:firewire ########################################### [100%] + 5:gspcav1 ########################################### [100%] + 6:qla2xxx ########################################### [100%] + 7:uvcvideo ########################################### [100%] + + +Before continuing with building the kernel modules check out the notes +below referring to some of them. + + +Build SL5 PSI Kernel-module RPMS On The Build System +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Now build the 64-bit modules:: + + # [gasser_m@tux50-64] + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # ./build_kernel_modules 2.6.18-164.11.1.el5 > \ + # UPDATE_LOG/20100125-build_kernel_modules-2.6.18-164.11.1.el5.x86_64.log 2>&1 + + +The following RPMS were built:: + + # cat ~/tmp/20090624-build_kernel_modules-2.6.18-128.1.14.el5.x86_64.output + + ... + --------------------------------------------------------------- + List of built kernel-modules for kernel 2.6.18-128.1.14.el5: + --------------------------------------------------------------- + + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-airprime-2.6.18-128.1.14.el5-2.6.18-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-airprime-2.6.18-128.1.14.el5xen-2.6.18-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-atl2-2.6.18-128.1.14.el5-1.0.40.4-4.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-atl2-2.6.18-128.1.14.el5xen-1.0.40.4-4.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-aufs-2.6.18-128.1.14.el5-0.20080605.cvs-5.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-aufs-2.6.18-128.1.14.el5xen-0.20080605.cvs-5.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-firewire-2.6.18-128.1.14.el5-2.6.18-2.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-firewire-2.6.18-128.1.14.el5xen-2.6.18-2.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-gspcav1-2.6.18-128.1.14.el5-01.00.20-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-gspcav1-2.6.18-128.1.14.el5xen-01.00.20-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-qla2xxx-2.6.18-128.1.14.el5-8.01.07.15-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-qla2xxx-2.6.18-128.1.14.el5xen-8.01.07.15-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-uvcvideo-2.6.18-128.1.14.el5-0.2.0-1.svn255.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-uvcvideo-2.6.18-128.1.14.el5xen-0.2.0-1.svn255.slp5.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-gpfs-2.6.18-128.1.14.el5-3.2.1-12.3.slp5.psi.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-openafs-2.6.18-128.1.14.el5-1.4.10-94.slp5.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-openafs-2.6.18-128.1.14.el5xen-1.4.10-94.slp5.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-VMwareTools-2.6.18-128.1.14.el5-6530-29999.slp5.x86_64.rpm + + List of files saved in /tmp/rpms_for_2.6.18-128.1.14.el5 ! + + +Note to Kernel Module Openafs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The openafs related build scripts are provided by Achim Gsell. + +If the kernel version is increased, the kernel-module-openafs has to +be built. + +If the Openafs version is increased, the kernel-module-openafs **AND** +the additional openafs RPMS (see list below) have to be built:: + + openafs + openafs-client + openafs-kpasswd + openafs-krb5 + + +One can use the following standalone script to built openafs modules. + +- `build-openafs.sl51.i386.sh` + + Standalone script for building and copying 32 bit openafs modules + +- `build-openafs.sl51.x86_64.sh` + + Standalone script for building and copying 64 bit openafs modules + + +Note to Kernel Module Uvcvideo +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If building fails, download the latest uvcvideo version and compile +again:: + + # cd ~/tmp/ + # svn checkout http://svn.berlios.de/svnroot/repos/linux-uvc/linux-uvc/trunk # see also in specfile + # mv trunk uvcvideo-svn255 + # tar cfzv uvcvideo-svn255.tar.gz uvcvideo-svn255/ + # scp uvcvideo-svn255.tar.gz tux50-64:/scratch/gasser_m/rpm_topdir/SOURCES/ + # ssh tux50-64 + # cd /scratch/gasser_m/rpm_topdir/SPECS/ + # vi uvcvideo.spec # Version: 0.2.0 + # %define date svn255 + # rpmbuild -ba --target x86_64 --define "kernel 2.6.18-92.1.13.el5" --define 'buildall 1' uvcvideo.spec + + ... + Wrote: /scratch/gasser_m/rpm_topdir/RPMS/x86_64/uvcvideo-0.2.0-1.svn255.slp5.src.rpm + Wrote: /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-uvcvideo-2.6.18-92.1.13.el5-0.2.0-1.svn255.slp5.x86_64.rpm + ... + + # echo "/scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-uvcvideo-2.6.18-92.1.13.el5-0.2.0-1.svn255.slp5.x86_64.rpm" >> \ + # /tmp/rpms_for_2.6.18-92.1.13.el5 + + +Don't forget to copy all the new modules to +`/afs/psi.ch/software/linux/dist/scientific/51/psi/all/`. + + +Check The Kernel Module Build Logs +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Check the log files for errors and verify that all required modules +were built:: + + # grep -i error ~/tmp/20090624-build_kernel_modules-2.6.18-128.1.14.el5.x86_64.output + ... + checking your OS... configure: error: No usable linux headers found at /lib/modules/2.6.18-128.1.14.el5PAE/build + + exit 1 + error: Bad exit status from /scratch/gasser_m/rpm_tmp/rpm-tmp.69701 (%build) + Bad exit status from /scratch/gasser_m/rpm_tmp/rpm-tmp.69701 (%build) + ... + + +This error is ok, as there is no x86_64 PAE kernel at all:: + + # check-set-of-built-kernel-modules.bash /tmp/rpms_for_2.6.18-128.1.14.el5 \ + # KERNEL_MODULES_TO_BUILD/sl5.i386.kms-to-be-built + # Not all kernel module RPMS were built! + # Check RPM(s) for: 'VMwareTools' + + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-airprime-2.6.18-128.1.14.el5-2.6.18-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-airprime-2.6.18-128.1.14.el5xen-2.6.18-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-atl2-2.6.18-128.1.14.el5-1.0.40.4-4.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-atl2-2.6.18-128.1.14.el5xen-1.0.40.4-4.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-aufs-2.6.18-128.1.14.el5-0.20080605.cvs-5.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-aufs-2.6.18-128.1.14.el5xen-0.20080605.cvs-5.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-firewire-2.6.18-128.1.14.el5-2.6.18-2.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-firewire-2.6.18-128.1.14.el5xen-2.6.18-2.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-gspcav1-2.6.18-128.1.14.el5-01.00.20-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-gspcav1-2.6.18-128.1.14.el5xen-01.00.20-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-qla2xxx-2.6.18-128.1.14.el5-8.01.07.15-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-qla2xxx-2.6.18-128.1.14.el5xen-8.01.07.15-1.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-uvcvideo-2.6.18-128.1.14.el5-0.2.0-1.svn255.slp5.x86_64.rpm + /scratch/gasser_m/rpm_topdir/RPMS/x86_64/kernel-module-uvcvideo-2.6.18-128.1.14.el5xen-0.2.0-1.svn255.slp5.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-gpfs-2.6.18-128.1.14.el5-3.2.1-12.3.slp5.psi.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-VMwareTools-2.6.18-128.1.14.el5-6530-29999.slp5.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-openafs-2.6.18-128.1.14.el5-1.4.10-94.slp5.x86_64.rpm + /afs/psi.ch/project/linux/dist/slp5/RPMS/x86_64/kernel-module-openafs-2.6.18-128.1.14.el5xen-1.4.10-94.slp5.x86_64.rpm + + +This also seems to be ok, as there was never a VMWare kernel module in +the repository for Xen and PAE kernel. + + +Copy The Kernel Module RPMS To The SL 5 Repository +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +Eventually, copy the built kernel module RPMS to the corresponding +PSI-ALL repository:: + + # cp -av `cat /tmp/rpms_for_2.6.18-128.1.14.el5` /afs/psi.ch/software/linux/dist/scientific/51/psi/all/ + + +Check whether the gpfs daemon and the gpfs kernel module RPMS were +copied, too, and have corresponding versions. + +Probably you have to build them first using +e.g. `build-gpfs.sl54.x86_64.sh` on tux50-64:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # ./build-gpfs.sl5x.x86_64.sh + # check-for-gpfs-occurence.bash 2.6.18-164.9.1.el5 3.2.1-16 4 51 + + # Begin checking for file occurence... + #/afs/psi.ch/software/linux/dist/scientific/51/nonfree/all/gpfs-3.2.1-16.4.slp5.psi.x86_64.rpm + # ok + #/afs/psi.ch/software/linux/dist/scientific/51/psi/all/kernel-module-gpfs-2.6.18-164.9.1.el5-3.2.1-16.4.slp5.psi.x86_64.rpm + # ok + #/afs/psi.ch/software/linux/dist/scientific/51/nonfree/all/gpfs-init-script-1.0-4.slp5.psi.x86_64.rpm + # ok + # End checking for file occurence. + + +Make The New Kernel Repository For SL5 +,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,,, + +The next two commands, `make kernel_all` and `make kernel`, will +process both architectures, i386 and x86_64. So you can run it only +once, after having built i386 and x86_64 kernel modules. + +Running `make kernel_all` will copy the built kernel module RPMS and +other kernel related RPMS from the corresponding ...-ALL to the +KERNEL-ALL directories, e.g.:: + + from: /afs/psi.ch/software/linux/dist/scientific/51/update.x86_64/all/ + to: /afs/psi.ch/software/linux/dist/scientific/51/kernel/all/ + + +Eventually `make kernel` will create the new kernel snapshot in +`/afs/psi.ch/software/linux/dist/scientific/51/kernel/`:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # make kernel_all > UPDATE_LOG/$(date +%Y-%m-%d)-make-kernel_all-2.6.18-164.11.1.el5.sl51.i386.x86_64.log 2>&1 + + # KERNEL_VER=2.6.18 KERNEL_REL=371.12.1.el5 make kernel + + +Follow the instructions at the end of the output of `make kernel` to +update symlinks, e.g:: + + # rm /afs/psi.ch/software/linux/dist/scientific/51/kernel/testing + # ln -s 2.6.18-371.12.1.el5 /afs/psi.ch/software/linux/dist/scientific/51/kernel/testing + + +Create Snapshots of Repositories +-------------------------------- + +Both architectures, i386 and x86_64, are treated by the following +commands. + +If new RPMS appear in a certain repository, which should be available +for the next update, a new snapshot is created for this repository. +The folder name of the snapshot will be equal to the current date. + +Create all snapshots at once (gfa excluded as Heiner Billich and Rene +Kapeller will create this snapshot). This can take up to one hour:: + + #[gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts + # nohup ./run_make_snapshots_all.sh & + + +As an alternative you could make a single snapshot of a certain +repository only. E.g. to make a snapshot of the `update` and `psi` +repos type:: + + # DIR=update make snapshot # DIR=update will set: ALL_DIRS="update.i386 update.x86_64" + # DIR=psi make snapshot + +`make snapshot` will execute +`/afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_snapshot`. +The command `createrepo` invoked in the shell script `.../mk_snapshot` +writes repodata for each snapshot to +e.g. `/afs/psi.ch/software/linux/dist/scientific/51/others/20090625/repodata/`. + +Release the snapshots for first level testing systems +----------------------------------------------------- + +The command `make release_testing` will update the respective symlinks +`.../testing` to the latest snapshots in all repos (again, except +`gfa`). + +Note: Because `make release_testing` is interactive, you should not +redirect the output to a file:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # make release_testing + +Before `make release_testing`: + +Note: The output below originates not from the same update as above, +this was 2008-08-27:: + + # [gasser_m@tux50] + # cd /afs/psi.ch/software/linux/dist/scientific/51/ + # \ls -l */testing + + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 cluster/testing -> 20080808 + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 enhanced/testing -> 20080808 + lrwxr-xr-x 1 billich ait 8 Aug 27 14:40 gfa/testing -> 20080827 + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 kde-redhat/testing -> 20080808 + lrwxr-xr-x 1 markushin ait 18 Aug 8 15:27 kernel/testing -> 2.6.18-92.1.10.el5 + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 nonfree/testing -> 20080808 + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 others/testing -> 20080808 + lrwxr-xr-x 1 markushin ait 8 Aug 14 15:23 psi/testing -> 20080814 + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 update.i386/testing -> 20080808 + lrwxr-xr-x 1 markushin ait 8 Aug 8 15:27 update.x86_64/testing -> 20080808 + + [gasser_m@tux50 51]$ \ls -l */current + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 cluster/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 enhanced/current -> 20080808 + lrwxr-xr-x 1 billich ait 8 Aug 27 14:40 gfa/current -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 kde-redhat/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 18 Aug 14 16:37 kernel/current -> 2.6.18-92.1.10.el5 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 nonfree/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 others/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 psi/current -> 20080814 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 update.i386/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 update.x86_64/current -> 20080808 + + +After `make release_testing`:: + + # [gasser_m@tux50] + # \ls -l */testing + + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 cluster/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 enhanced/testing -> 20080827 + lrwxr-xr-x 1 billich ait 8 Aug 27 14:40 gfa/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 kde-redhat/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 18 Aug 28 14:58 kernel/testing -> 2.6.18-92.1.10.el5 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 nonfree/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 others/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 psi/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 update.i386/testing -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 28 14:58 update.x86_64/testing -> 20080827 + + [gasser_m@tux50 51]$ \ls -l */current + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 cluster/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 enhanced/current -> 20080808 + lrwxr-xr-x 1 billich ait 8 Aug 27 14:40 gfa/current -> 20080827 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 kde-redhat/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 18 Aug 14 16:37 kernel/current -> 2.6.18-92.1.10.el5 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 nonfree/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 others/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 psi/current -> 20080814 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 update.i386/current -> 20080808 + lrwxr-xr-x 1 gasser_m ait 8 Aug 14 16:37 update.x86_64/current -> 20080808 + + +Now, the `testing` symlinks point to the latest snapshots, while the +`current` symlinks still point to the previous snapshots. + + +Make First Tests +---------------- + +Manually update selected `testing` hosts (see `/etc/sysconfig/psi` and +`/etc/yum.conf`) with yum. The `testing` string is set in +`/etc/sysconfig/psi` and `/etc/yum.conf` (i.e. your computer is +looking for new RPMS in the `testing` snapshots):: + + # yum clean all + # yum update + +If there's a new kernel, reboot into this new kernel and especially +check whether the new kernel-module-openafs is working and AFS was +mounted. + +- Note to the `psi-update` script + +`psi-update` will not work at this point, because it's udpating only +if the PSI version has changed, what will be done later (see "Create A +New PSI Version Of SL51" below). `psi-update` will get the script +`yum_update` from our master, pxeserv01, see also `/etc/fstab`. The +script `yum_update` will be saved locally as +`/usr/sbin/psi-yum_update`. Afterwards `psi-yum_update` will be +executed locally. + + +Create A New PSI Version Of SL51 And Release It For Testing Systems +------------------------------------------------------------------- + +In this section a new PSI version is created and released for testing +systems. By default, Green Testing PCs will be auto updated during +the following night. + +The procedure shown here has to be repeated for all SL5 class/subclass +combinations. Contemporary there are three of them: + +1. Desktop/Stable +2. Desktop/Enhanced +3. Cnode/Stable + +To get an overview list the classes directories:: + + # [gasser_m@pc7377 Stable]$ ll -rt /afs/psi.ch/software/linux/dist/scientific/51/classes/* + + /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop: + total 10 + drwxr-xr-x 2 beyerle ait 2048 Jan 19 2008 StableTesting + drwxr-xr-x 2 beyerle ait 2048 Jan 19 2008 EnhancedTesting + drwxr-xr-x 15 beyerle ait 4096 Jul 2 17:11 Enhanced + drwxr-xr-x 15 beyerle ait 2048 Aug 11 14:19 Stable + + /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode: + total 4 + drwxr-xr-x 2 beyerle ait 2048 Jan 19 2008 StableTesting + drwxr-xr-x 15 beyerle ait 2048 Jul 2 17:11 Stable + + +Note: To change the list of RPMS of a certain class edit the +corresponding package list. + +E.g.: To add RPMS in update version 19 of SL51 Desktop/Stable edit +`list.Stable.v19`:: + + # vi /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/list.Stable.v19 + +IMPORTANT: If you add RPMS to the list, update also the RPM lists used +in the kickstart installation:: + + # vi /afs/psi.ch/software/linux/dist/scientific/51/kickstart/custom/DesktopStablei386/yum_install.conf + # vi /afs/psi.ch/software/linux/dist/scientific/51/kickstart/custom/DesktopStablex86_64/yum_install.conf + +- Note: The following tasks can also be performed using the script + `create-new-psi-version.bash`. + + +Desktop/Stable: Release Desktop Stable Testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create folder for Version 19 by running make class:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/ + # cp list.Stable.v18 list.Stable.v19 + + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # CLASS=Desktop SUBCLASS=Stable version=19 LIST=list.Stable.v19 make class + + ###{ begin output make class + Populating Class directory ... + TOP_DIR=/afs/psi.ch/software/linux/dist/scientific/51 \ + /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class + + Configuration file /afs/psi.ch/software/linux/dist/scientific/51/scripts/dist-config + Running /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class ... + create version and release file + copy list.Stable.v19 to list + ------------------------------------------------------------------------------- + The directory /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMS-20080811 has been populated. + + RPMSv19 links to RPMS-20080811 + + Please check + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMS-20080811/version + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMS-20080811/release + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMS-20080811/list + + If you like to display a message for the user (one line) put it into + emacs /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMS-20080811/message + + If you want to release `testing`, link RPMSTesting to RPMSv19: + rm -f /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMSTesting + ln -s RPMSv19 /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMSTesting + + ------------------------------------------------------------------------------- + ... End of /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class + ###} end output make class + + +Now release it:: + + # rm -f /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMSTesting + # ln -s RPMSv19 /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Stable/RPMSTesting + + +Desktop/Enhanced: Release Desktop Enhanced Testing (also a lot of nonfree etc. stuff) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create folder for Version 19 by running `make class`:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/ + # cp list.Enhanced.v18 list.Enhanced.v19 + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # CLASS=Desktop SUBCLASS=Enhanced version=19 LIST=list.Enhanced.v19 make class + + ###{ begin output + Populating Class directory ... + TOP_DIR=/afs/psi.ch/software/linux/dist/scientific/51 \ + /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class + + Configuration file /afs/psi.ch/software/linux/dist/scientific/51/scripts/dist-config + Running /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class ... + create version and release file + copy list.Enhanced.v19 to list + ------------------------------------------------------------------------------- + The directory /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMS-20080811 has been populated. + + RPMSv19 links to RPMS-20080811 + + Please check + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMS-20080811/version + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMS-20080811/release + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMS-20080811/list + + If you like to display a message for the user (one line) put it into + emacs /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMS-20080811/message + + If you want to release "testing", link RPMSTesting to RPMSv19: + rm -f /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMSTesting + ln -s RPMSv19 /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMSTesting + + ------------------------------------------------------------------------------- + ... End of /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class + ###} end output + + +Now release it:: + + # rm -f /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMSTesting + # ln -s RPMSv19 /afs/psi.ch/software/linux/dist/scientific/51/classes/Desktop/Enhanced/RPMSTesting + + +Cnode/Stable: Release Cnode Stable Testing +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create folder for Version 19 by running `make class`:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/ + # cp list.Stable.v18 list.Stable.v19 + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # CLASS=Cnode SUBCLASS=Stable version=19 LIST=list.Stable.v19 make class + + ###{ begin output + Populating Class directory ... + TOP_DIR=/afs/psi.ch/software/linux/dist/scientific/51 \ + /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class + + Configuration file /afs/psi.ch/software/linux/dist/scientific/51/scripts/dist-config + Running /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class ... + create version and release file + copy list.Stable.v19 to list + ------------------------------------------------------------------------------- + The directory /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMS-20080811 has been populated. + + RPMSv19 links to RPMS-20080811 + + Please check + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMS-20080811/version + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMS-20080811/release + cat /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMS-20080811/list + + If you like to display a message for the user (one line) put it into + emacs /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMS-20080811/message + + If you want to release "testing", link RPMSTesting to RPMSv19: + rm -f /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMSTesting + ln -s RPMSv19 /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMSTesting + + ------------------------------------------------------------------------------- + ... End of /afs/psi.ch/software/linux/dist/scientific/51/scripts/mk_class + ###} end output + + +Now release it:: + + # rm -f /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMSTesting + # ln -s RPMSv19 /afs/psi.ch/software/linux/dist/scientific/51/classes/Cnode/Stable/RPMSTesting + + +Test the Update On Testing Systems +---------------------------------- + +On a testing system run:: + + [root@tux50] + # psi-update + + +Release The Update PSI Wide For Productive Systems +-------------------------------------------------- + +Run:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts/ + # make current_equal_testing + + +Refresh symbolic links in the `RPMS_all` folder to all respective +RPMS:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51/scripts + # make rpms_all + + +Test The Update On Productive Systems +------------------------------------- + +On a productive (=current) system run:: + + # psi-update + + +Update The Webpages +=================== + +Reference +--------- + +https://wiki.intranet.psi.ch/AIT/LinuxRegularUpdate#Update_the_Webpages + +*Possibly it's better to move the reference to the top Reference +section. This section is still in a very sketch state anyway.* + + +General Info to Webpages Providing SL Update Infos +-------------------------------------------------- + +The website is public to PSI.#??? or to everybody? + +The site provides information about the SL update progress for users +at PSI. + +Location of the website: + + On AFS: /afs/psi.ch/project/ait/www/services/linux/updates/ + On WWW: http://ait.web.psi.ch/services/linux/updates/ + + +Update the following Webpages: + +- http://ait.web.psi.ch/services/linux/updates/ + +- http://ait.web.psi.ch/services/linux/updates/update_sl5.html + +- http://ait.web.psi.ch/services/linux/updates/update_sl4.html + +- http://ait.web.psi.ch/services/linux/updates/update_sl3.html + + +- Objective + +Show the updated RPMS between current and the release before. Reduce +amount of info to a reasonable minimum and represent clearly for +users. Don't show RPMS, which are in the repository but will not be +installed because of a newer version of this RPM in the same snapshot. + + +Script location: /afs/psi.ch/project/ait/www/services/linux/updates/ + find_new_rpms_between 20080626 51 18 20080808 51 19 The command + above will not yet work on SL5, because of directory layout + changes between SL4 and SL5. For now we will take another + procedure to prepare the HTML files. + +The following command will show some first scratch of an alternative +way to get the list with updated RPMS:: + + # cd /afs/psi.ch/software/linux/dist/scientific/51 + # diff <( ls -1 */testing/ | sort ) <( ls -1 */current/ | sort ) | grep '^<' | sed -e 's/.i.86.rpm//' -e 's/.x86_64.rpm//' | uniq + +What do we need? In SL5 we have the following classes/subclasses:: + + # + + ¦---Stable + ¦-Cnode---¦ + ¦ ¦---StableTesting + ¦ + ¦ + sl5---¦ + ¦ ¦--Stable + ¦ ¦ + ¦ ¦--StableTesting + ¦-Desktop-¦ + ¦--Enhanced + ¦ + ¦--EnhancedTesting + + + ls -1 */testing/ | grep -v testing | grep -v x86_64 | sort > ~/tmp/sl51-v19-ls-asterisk-testing-sort-out + ls -1 */current/ | grep -v current | grep -v x86_64 | sort > ~/tmp/sl51-v19-ls-asterisk-current-sort-out + /afs/psi.ch/user/g/gasser_m/tmp/ + mengen.py -D sl51-v19-ls-asterisk-testing-sort-out sl51-v19-ls-asterisk-current-sort-out > sl51-v19-mengen-out + get-latest-RPM-from-RPM-list.pl sl51-v19-mengen-out > sl51-v19-updated-RPMS.list + + +From sl51-v19-updated-RPMS.list take the list to insert into the HTML +update site. Edit file +`/afs/psi.ch/project/ait/www/services/linux/updates/update_sl5.html`. + + +Are all clients up-to-date? +--------------------------- + +Login to pxeserv01. + +Note to puppet and `/etc/sysconfig/psi` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Even puppet and not cfengine is running on SL5, latest copies of +`ANYHOST:/etc/sysconfig/psi` from SL3, SL4 and SL5 systems are put to +`pxeserv01:/opt/cfengine/sysconfig/`:: + + # cd /opt/cfengine/scripts + # ./find_hosts_with_old_version.sh 98 71 20 + + running... + ./cfengine.lcmeg01:VERSION=70 + ./cfengine.lclth01:VERSION=70 + ./cfengine.lclev03:VERSION=70 + ./cfengine.pc7148:VERSION=18 + ./cfengine.lclev01:VERSION=70 + ./cfengine.lclth04:VERSION=70 + ./cfengine.pc6702:VERSION=69 + ./cfengine.lclth07:VERSION=70 + ./cfengine.pc3384:VERSION=97 + ./cfengine.slsnedi1:VERSION=17 + ./cfengine.pc5082:VERSION=91 + ./cfengine.lpc4358:VERSION=69 + ./cfengine.lclev05:VERSION=70 + ./cfengine.lclth08:VERSION=70 + ./cfengine.lclth02:VERSION=70 + ./cfengine.llc6:VERSION=69 + ./cfengine.lclrs11:VERSION=69 + ./cfengine.pc5835:VERSION=96 + ./cfengine.lclth06:VERSION=70 + ./cfengine.tux40e:VERSION=70 + ./cfengine.lclev02:VERSION=70 + ./cfengine.lclth03:VERSION=70 + ./cfengine.pc4426:VERSION=17 + ./cfengine.pcmic01:VERSION=70 + ./cfengine.lclth05:VERSION=70 + done! + + +If a host is not up-to-date, login to the host and run manually:: + + # psi-update + + +You may also want to check the logs in `/var/log/update/` diff --git a/admin-guide/legacy/misc/vpnclientlinux.rst b/admin-guide/legacy/misc/vpnclientlinux.rst new file mode 100644 index 00000000..9a18d1ce --- /dev/null +++ b/admin-guide/legacy/misc/vpnclientlinux.rst @@ -0,0 +1,46 @@ +VPN Client on Linux +=================== + +References +---------- + +- vpnc manpage + +Requirements +------------ + +- VPN Client Package + + +Procedure +--------- + +Installation +~~~~~~~~~~~~ + +Login as localadmin (Green PC) or root (Red PC) and install the VPN +related packages:: + + # yum install vpnclient-psi + # yum install vpnc + +Configuration +~~~~~~~~~~~~~ + +For Users +......... + +You don't have to configure anything manually, the configuration was +done by installing the `vpnclient-psi` package. + +For Packager +............ + +The default configuration files are `/etc/vpnc/default.conf` and +`/etc/vpnc.conf`. + +The Cisco VPN client config file `vpn-psi.pcf` for PSI is provided by +Tobias Marx. The command `/usr/share/doc/vpnc-0.5.3/pcf2vpnc` is used +to convert the `.pcf` to `.conf`:: + + # perl /usr/share/doc/vpnc-0.5.3/pcf2vpnc vpn-psi.pcf vpn-psi.conf diff --git a/admin-guide/legacy/monitoring.rst b/admin-guide/legacy/monitoring.rst new file mode 100644 index 00000000..1af84102 --- /dev/null +++ b/admin-guide/legacy/monitoring.rst @@ -0,0 +1,34 @@ +Monitoring and Reporting +======================== + + +Cron jobs +--------- + +Cron jobs send mail on error, usually to `linuxmaster@psi.ch`, a +distribution list. + + +Nagios/Icinga +------------- + + +Ganglia +------- + + +Other +----- + +Some systems dump information in +``/afs/psi.ch/service/linux/statistics/rawdata``. Others save it to +``/afs/psi.ch/intranet/Controls/tmp/sysreport/PSI``. + +The PXE server `pxeserv01` regularly runs a script, +`/afs/psi.ch/service/linux/tftpboot/tools/script/pxe_script`, which copies +`/var/log/tftp.log` to `/afs/psi.ch/service/linux/tftpboot/tools/log/`, +compresses it, and produces statistics, which are saved as `pxeStatistik-$(date ++%Y%m%d).txt`. + +The script is currently run as user `vojisavljevic` and the run is configured in +that user's crontab. diff --git a/admin-guide/legacy/puppet.rst b/admin-guide/legacy/puppet.rst new file mode 100644 index 00000000..10a71c92 --- /dev/null +++ b/admin-guide/legacy/puppet.rst @@ -0,0 +1,8 @@ +Puppet +====== + +There have been and still are several instances of Puppet PSI. + +- ``pxeserv01`` (obsolete, no puppetmaster running) +- ``psi-puppet3`` (used by Controls-IT) +- ``psi-puppet4`` diff --git a/admin-guide/legacy/services.rst b/admin-guide/legacy/services.rst new file mode 100644 index 00000000..94d31a31 --- /dev/null +++ b/admin-guide/legacy/services.rst @@ -0,0 +1,19 @@ +Services +======== + +Login cluster +------------- + +The login cluster allows users to run interactive programs. The +cluster consists of several nodes `llcN.psi.ch`, where N is 1, 2, +or 3. There is also a load-balancer, `llclb1.psi.ch`, which uses IPVS +with a round robin policy to distribute incoming connections. + + +Jump hosts +---------- + +Many servers can only be accessed via SSH through one of the two jump +hosts, `wmgt01.psi.ch` and `wmgt02.psi.ch`. These two systems require +two-factor authentication (currently using a Cryptocard dongle) and +offer a very restricted environment. diff --git a/admin-guide/legacy/software.rst b/admin-guide/legacy/software.rst new file mode 100644 index 00000000..be93dbd5 --- /dev/null +++ b/admin-guide/legacy/software.rst @@ -0,0 +1,10 @@ +Software +======== + +.. toctree:: + :maxdepth: 1 + + software/repositories + software/packaging + software/modules + diff --git a/admin-guide/legacy/software/modules.rst b/admin-guide/legacy/software/modules.rst new file mode 100644 index 00000000..cdeec908 --- /dev/null +++ b/admin-guide/legacy/software/modules.rst @@ -0,0 +1,26 @@ +Modules +======= + +The Scientific Computing team provides a number of programs using Modules. The +Modules configuration files and the corresponding software are stored on AFS. + +To use Modules it is necessary to create a symlink:: + + ln -snf /afs/psi.ch/sys/psi.x86_64.slp6/ /opt/psi + +where ``x86_64.slp6`` describes the architecture and OS of the system the +modules should be used on. It is the output of ``fs sysname``. Every session +needs to ``source /opt/psi/config/profile.bash`` as well. + +The available modules can be listed by running:: + + module avail + +Note that the modules are hierarchical, i.e. only the modules that can actually +be loaded are listed. Some modules require that other modules are loaded first, +e.g. a certain version of gcc, and are listed only after that has been done. + +Modules are loaded by running:: + + module load gcc/4.7.3 + diff --git a/admin-guide/legacy/software/packaging.rst b/admin-guide/legacy/software/packaging.rst new file mode 100644 index 00000000..8ac7239f --- /dev/null +++ b/admin-guide/legacy/software/packaging.rst @@ -0,0 +1,35 @@ +Packaging +========= + +Currently, the two most important custom packages are OpenAFS and GPFS +(see below), but there are many others. The sources and spec files +for RPMs are stored on AFS in +`/afs/psi.ch/project/linux/src/scientific/RPMS/` and +`/afs/psi.ch/project/linux/src/RPMS/`. They should be - and partially +have been - moved to Gitlab, group `linux-packages`. + + +Build hosts +----------- + + +OpenAFS +------- + + +GPFS +---- + +The source files for GPFS as well as certain tools for building the +packages are stored in +`/afs/psi.ch/project/linux/src/scientific/RPMS/gpfs/`. The +`README.build` file in that directory contains instructions on how to +build GPFS for a given combination of GPFS version and kernel version. + +The files `default-version.${release}.${architecture}` contain the +GPFS Release and supported versions for the specific `${release}` and +`${architecture}`, e.g.:: + + GPFSVERSION="3.5.0-24 4.1.1-4" + GPFSRELEASE=7 + diff --git a/admin-guide/legacy/software/repositories.rst b/admin-guide/legacy/software/repositories.rst new file mode 100644 index 00000000..96b68919 --- /dev/null +++ b/admin-guide/legacy/software/repositories.rst @@ -0,0 +1,245 @@ +Repositories +============ + +A number of repositories are currently mirrored on AFS under +``/afs/psi.ch/software/mirror`` (``$MIRROR``), in particular the following +versions of Scientific Linux, both 32 and 64 bit: 5.7, 6.0, 6.4, and 6.x. + +The repositories are accessible via HTTP at http://linux.web.psi.ch/. + +They are stored in ``$MIRROR/scientific``, each subdirectory of which +is a mount point for a separate AFS volume. This is done because +smaller AFS volumes are easier to handle (e.g. when moving them +between fileservers). + +Each mirror, e.g. ``$MIRROR/scientific/60/epelp/`` contains a +subdirectory ``all``, which contains the packages that we actually +want in our YUM repositories. + +Repository management as well as package building can be done on the +various ``tux*.psi.ch`` servers. + +Further documentation on repository management can be found in +``/afs/psi.ch/project/linux/doc``. This documentation will eventually +be included in this document. + +The directory ``$MIRROR/scientific/scripts`` contains scripts for +various tasks related to managing the Scientific Linux repositories. +It is a working copy of a [git +repository](http://git.psi.ch/linux-dist/sl-scripts). + + +Tools +----- + +There are several scripts that are used to maintain/update the various +repositories. + + +``sync_updates.sh`` +~~~~~~~~~~~~~~~~~~~ + +This script copies new packages from the SL mirror to the PSI distribution +directories, and runs ``createrepo --update`` to update the repository metadata. + +Information on the directories is read from a file ``dist-config`` in the +current working directory. + + +``update_symlinks`` +~~~~~~~~~~~~~~~~~~~ + + + + + +Updates +------- + +To release updates to the existing repositories, the steps below have to be +performed. The value of ``DIST_DIR`` is the base directory of the distribution +to be updated, i.e. ``/afs/psi.ch/software/linux/dist/scientific/xx/``, where +``xx`` is one of ``57``, ``60``, or ``64``. + +1. Update add-on repositories +2. cd "${DIST_DIR}/scripts" +3. ./sync_updates.sh +4. ./update_symlinks.sh +5. ./create_snapshots.sh alldirs +6. ./release_unstable.sh +7. ./incr_version.sh +8. ./update_version_info.sh +9. test new unstable release +10. ./release.sh testing +11. ./update_version-info.sh +12. test testing release +13. ./release.sh stable +14. ./update_version-info.sh + +The sections below describe each step in detail. The value of ``PRJ_DIR`` is +``/afs/psi.ch/project/linux/``. + + +Kernel updates +~~~~~~~~~~~~~~ + +If there is a new kernel, some of the modules need to be rebuilt. For SL 5.7 +there is a script in the ``scripts`` subdirectory taking care of this: +``build_kernel_modules.sh``. + + +Update add-on repositories +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +GPFS +,,,, + + rsync --archive --verbose ${PRJ_DIR}/dist/slp6/RPMS/*/kmod-gpfs* "${DIST_DIR}/psi/all" + rsync --archive --verbose ${PRJ_DIR}/dist/slp6/RPMS/*/gpfs* "${DIST_DIR}/nonfree/all" + +Notes: + +- Don't know why the kernel modules for GPFS are in 'psi' but the GPFS user-land + software is in 'nonfree'. +- Hans-Christian is responsible for building RPMs + + +OpenAFS +,,,,,,, + +Note: OpenAFS version on tux50 and tux50-64 is 1.4.x. On all other systems it is 1.6.x. + +Build OpenAFS ++++++++++++++ + +On tux50, tux50-64, tux60-tux60-64, tux70. + +Either:: + + rsync --verbose ${PRJ_DIR}/dist/slp6/RPMS/*/kernel-module-openafs-* "${DIST_DIR}/psi/all" + +or: copy decicated versions + +Notes: Achim is responsible for building OpenAFS RPMs. + +Checklist ++++++++++ + +New version available? If yes, build binaries: + +========= ===== ========= ======== +OS New? Compiled Copied? +--------- ----- --------- -------- +tux50 no +tux50-64 no +tux60 yes yes yes +tux60-64 yes yes yes +tux70-64 yes yes yes +========= ===== ========= ======== + +New kernel or version available? If yes, install kernel, build module: +========= ===== ========= ======== +OS New? Compiled Copied? +--------- ----- --------- -------- +tux50 no - - +tux50-64 no - - +tux60 yes yes yes +tux60-64 yes yes yes +tux70-64 yes yes yes +========= ===== ========= ======== + +ZFS +,,, + +ZFS kernel modules are available for EL7 only! + +Sync from master repository ++++++++++++++++++++++++++++ + +Run on tux70-64 as normal user:: + + reposync --repoid=zfs --norepopath --download_path /afs/psi.ch/software/mirror/zfsonlinux/7/x86_64 + +Build kmod +++++++++++ + +Build on tux70-64 as root. + +Boot into the right (newest) kernel! This is the kernel we are going to build +the modules for. Run:: + + # set some variables + $ ZFS_VERS='x.y.z' + $ ZFS_REL='r' + $ ZFS_REPO_DIR='/afs/psi.ch/software/linux/dist/scientificlinux/7x/x86_64/zfs/' + $ DIST='el7' + $ ARCH='x86_64' + + $ cd /usr/src/spl-$ZFS_VERS + $ ./configure + $ make rpm-utils rpm-kmod + + # Install the spl packages, they are required to build zfs. + $ yum localinstall \ + kmod-spl-devel-$ZFS_VERS-$ZFS_REL.$DIST.$ARCH.rpm \ + kmod-spl-devel-kernel-$ZFS_VERS-$ZFS_REL.$DIST.$ARCH.rpm \ + kmod-spl-kernel-$ZFS_VERS-$ZFS_REL.$DIST.$ARCH.rpm \ + spl-$ZFS_VERS-$ZFS_REL.$DIST.$ARCH.rpm + + $ cd ../zfs-x.y.z + $ ./configure + $ make rpm-utils rpm-kmod + + # you need an AFS-token to copy the files! + $ klog.openafs USERNAME + + # for a new ZFS version do + $ cp -v spl-$ZFS_VERS/*.x86_64.rpm "$ZFS_REPO_DIR" + $ cp -v zfs-$ZFS_VERS/*.x86_64.rpm "$ZFS_REPO_DIR" + + # to copy kernel modules only, do + $ cp -v spl-$ZFS_VERS/kmod-*-$(uname -r)*.x86_64.rpm "$ZFS_REPO_DIR" + $ cp -v zfs-$ZFS_VERS/kmod-*-$(uname -r)*.x86_64.rpm "$ZFS_REPO_DIR" + + # update repo + $ cd "$ZFS_REPO_DIR" + $ createrepo --update . + +See also: ``_ + +Checklist ++++++++++ + +If there is a new version: Are the RPM of the new versions of spl-x.y.z and +zfs-x.y.z in ``/afs/psi.ch/software/linux/dist/scientificlinux/7x/x86_64/zfs/``? + +Are the kmod-RPM's for the newest kernel in +``/afs/psi.ch/software/linux/dist/scientificlinux/7x/x86_64/zfs/``? + +Flash Player +,,,,,,,,,,,, + +Download +++++++++ + +Current Flash-Player must be downloaded from `Adobe +`_ and copied to +``${DIST_DIR}/nonfree/all``. + +Checklist ++++++++++ + +Is the newest version installed in +``/afs/psi.ch/software/linux/dist/scientific/xx/nonfree/all/`` (``xx`` in +``57``, ``60``, ``64``)? + + +NVidia +,,,,,, + +syslog-ng +,,,,,,,,, + +openntpd +,,,,,,,, + diff --git a/admin-guide/legacy/storage.rst b/admin-guide/legacy/storage.rst new file mode 100644 index 00000000..78186451 --- /dev/null +++ b/admin-guide/legacy/storage.rst @@ -0,0 +1,10 @@ +Storage +======= + +Currently, data is generally stored on AFS. In particular: + +- ``/afs/psi.ch/software/mirror``: Mirrors of external repositories and + software, e.g. CentOS, EPEL. +- ``/afs/psi.ch/software/linux/kickstart``: Kickstart files and related + tools/packages. +- ``/afs/psi.ch/software/linux/dist/``: YUM repositories used at PSI. diff --git a/admin-guide/make.bat b/admin-guide/make.bat new file mode 100644 index 00000000..e2b70b4a --- /dev/null +++ b/admin-guide/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\LinuxInfrastructure.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\LinuxInfrastructure.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/admin-guide/mgmt-tools.rst b/admin-guide/mgmt-tools.rst new file mode 100644 index 00000000..a4027d90 --- /dev/null +++ b/admin-guide/mgmt-tools.rst @@ -0,0 +1,10 @@ +Management Tools +================ + +.. toctree:: + :maxdepth: 2 + + mgmt-tools/sysdb + mgmt-tools/bob + mgmt-tools/sphinx + mgmt-tools/puppetdb diff --git a/admin-guide/mgmt-tools/bob.rst b/admin-guide/mgmt-tools/bob.rst new file mode 100644 index 00000000..db676d3f --- /dev/null +++ b/admin-guide/mgmt-tools/bob.rst @@ -0,0 +1,99 @@ +bob - a CLI sysdb client +======================== + +``bob`` is a command-line client for sysdb. It supports adding, updating, and +retrieving information about environments, nodes, MAC addresses and attributes. +It can authenticate using Kerberos credentials or username/password pairs. + + +Installation and setup +---------------------- + +For production use of bob there will be RPMs for bob and its dependencies. + +For the moment the steps are the following:: + + yum -y install python-setuptools python-requests-kerberos + git clone git@git.psi.ch:linux-infra/bob.git + cd bob + python setup.py install + + +Configuration +------------- + +``bob`` takes a number of arguments, one of which is the base URL of the sysdb +instance. It can be passed via ``--url BASEURL`` on the command-line, or using +the environment variable ``PSI_BOB_URL``. Therefore it is useful include the +following in your ``.bash_profile``:: + + PSI_BOB_URL=https://boot00.psi.ch/ + +Development +----------- +For development, the easiest way to use bob is the following:: + + pip install --user click + git clone XXX + cd YYY + pip install --user --editable . + +This will place a script ``bob`` in ``~/.local/bin``, which will reference the +code in the working directory of the repository clone. This way, local changes +in the source are effective immediately. It might be a good idea to use +``virtualenv`` to avoid installing dependencies system-wide. + +In addition to the ``PSI_BOB_URL`` it can be handy to also have the following +in your ``.bash_profile``:: + + alias bobtest='PSI_BOB_URL=https://boot00-test.psi.ch/ bob' + alias bobdev='PSI_BOB_URL=http://localhost:5000/ bob' + +During development sysdb usually listens on ``localhost:5000`` and doesn't use +SSL, explaining the second alias. It also doesn't support authentication, +instead expecting to find the username in the ``REMOTE_USER`` header. The latter +can be set using the ``--fake-user`` option in bob or using the ``-H`` option in +cURL:: + + bobdev --fake-user kaminski_k node set-attr foo.psi.ch ipxe_installer=rhel72server + + curl -X PUT -H REMOTE_USER:talamo_i http://localhost:5000/sysdb/v1/ + +Attributes +---------- + +The following attributes can be set for a node: + ++------------------------+------------------+-----------+------------------------------------------------------------------------------+ +| attribute name | sample value | mandatory | meaning | ++========================+==================+===========+==============================================================================+ +| ``ipxe_installer`` | rhel73installer | yes | the installation entry to use at installation time via IPXE | ++------------------------+------------------+-----------+------------------------------------------------------------------------------+ +| ``network`` | static | yes | network setup of the installed system. can be ``static`` or ``dhcp`` | ++------------------------+------------------+-----------+------------------------------------------------------------------------------+ +| ``puppet_env`` | prod | yes | puppet environment | ++------------------------+------------------+-----------+------------------------------------------------------------------------------+ +| ``puppet_role`` | ``role::server`` | yes | puppet role of the node. String should start with ``role::`` | ++------------------------+------------------+-----------+------------------------------------------------------------------------------+ +| ``puppet_group`` | computing | no | defines the group for the hiera values. If not set takes the ``default`` one | ++------------------------+------------------+-----------+------------------------------------------------------------------------------+ + + +root password +~~~~~~~~~~~~~ + +The root password can be set with the attribute ``rootpw``. The value +of the attribute must be the password hash, and can be generated with the command +``openssl passwd -1 "this is the password"`` + +partitions +~~~~~~~~~~ + +Partition schema can be passed as a url using the ``partitions`` attribute. +It must be a publicly accessible url and its content will be copied into the +kickstart section related to the partition. + +The usage of this attribute is generally discouraged and is provided to cover +only the cases that are not actually already covered by the installation system, +eg. the software raid configuration. + diff --git a/admin-guide/mgmt-tools/puppetdb.rst b/admin-guide/mgmt-tools/puppetdb.rst new file mode 100644 index 00000000..8596ded4 --- /dev/null +++ b/admin-guide/mgmt-tools/puppetdb.rst @@ -0,0 +1,52 @@ +puppetdb +======== + +Authentication +-------------- + +We need a client certificate (including the key) accepted by the Puppet server +for authentication. On Puppet-enabled nodes the node's certificate works, ie + +- Certificate: ``/etc/puppetlabs/puppet/ssl/certs/$(hostname -f).pem`` +- Key: ``/etc/puppetlabs/puppet/ssl/private_keys/$(hostname -f).pem`` + +These can be supplied to ``curl(1)`` using the ``--key``, ``--cert``, and +``--cacert`` options:: + + curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \ + --key /etc/puppetlabs/puppet/ssl/private_keys/$(hostname -f).pem \ + --cert /etc/puppetlabs/puppet/ssl/certs/$(hostname -f).pem \ + https://puppet00.psi.ch:8080/pdb/query/v4/nodes + + +Queries +------- + +There are several API endpoints, eg. ``/pdb/query/v4`` (note that there is no +``/`` at the end), or ``/pdb/query/v4/nodes``. + + +Examples +-------- + +First, let's define a function to simplify the queries:: + + function pdb { + local pql=$1 + + curl --cacert /etc/puppetlabs/puppet/ssl/certs/ca.pem \ + --key /etc/puppetlabs/puppet/ssl/private_keys/$(hostname -f).pem \ + --cert /etc/puppetlabs/puppet/ssl/certs/$(hostname -f).pem \ + -H content-type:application/json --data "{ \"query\": \"$pql\" }" \ + https://puppet00.psi.ch:8080/pdb/query/v4 | json_reformat + } + + +List all nodes:: + + pdb "nodes[certname] { order by certname }" + + +List environments and times of the last Puppet run:: + + pdb "reports[certname,environment,start_time,end_time] { order by certname }" diff --git a/admin-guide/mgmt-tools/sphinx.rst b/admin-guide/mgmt-tools/sphinx.rst new file mode 100644 index 00000000..6811db6c --- /dev/null +++ b/admin-guide/mgmt-tools/sphinx.rst @@ -0,0 +1,40 @@ +Sphinx +====== + +`Sphinx `_ is a tool for generating +documentation from `reStructuredText +`_. + +It can generate various formats, including HTML and PDF. + + +Installing Sphinx +----------------- + +On RHEL 7 it is enough to install the ``python-sphinx`` package:: + + yum install python-sphinx + + +Editing +------- + +On Linux with the ``inotify-tools`` it is easy to have the documentation recompiled +automatically while editing. Just run the following in the base directory of the +documentation:: + + inotifywait --monitor --recursive --event close_write --exclude '_build' . | while read l; do make html;done + +On OSX you can install `fswatch `_ and then run the following:: + + fswatch --exclude=_build --monitor=fsevents_monitor --recursive --event Updated --event Created --event Renamed .| while read l; do make html ;done + +An even better alternative is `sphinx-autobuild +`_, which can be installed using +pip:: + + pip install sphinx-autobuild + +It can then be called like this:: + + sphinx-autobuild /path/to/sphinx/repo /path/to/sphinx/repo/_build/html/ diff --git a/admin-guide/mgmt-tools/sysdb.rst b/admin-guide/mgmt-tools/sysdb.rst new file mode 100644 index 00000000..24992d6b --- /dev/null +++ b/admin-guide/mgmt-tools/sysdb.rst @@ -0,0 +1,20 @@ +sysdb +===== + +sysdb is a simple database holding information relevant to system deployment, +including + +#. a MAC to FQDN mapping + +#. whether to boot from local disk or install + +#. if installation is requested, which distribution/release to install + +#. which environment a system belongs to, and who can manage the environment + +#. arbitrary key-value pairs which can be used to store additional information + like the Puppet role of a system. + +sysdb runs on the boot server, ie. ``boot00.psi.ch`` (production) and +``boot00-test.psi.ch`` (testing). + diff --git a/admin-guide/more.rst b/admin-guide/more.rst new file mode 100644 index 00000000..6fe14c04 --- /dev/null +++ b/admin-guide/more.rst @@ -0,0 +1,8 @@ +More +==== + + +.. toctree:: + :maxdepth: 2 + + more/network diff --git a/admin-guide/more/network.rst b/admin-guide/more/network.rst new file mode 100644 index 00000000..d7cec891 --- /dev/null +++ b/admin-guide/more/network.rst @@ -0,0 +1,9 @@ +Network +------- + +The production infrastructure systems, eg. ``puppet00.psi.ch``, are not +reachable from all networks. One example would be the DMZ. + +To allow the deployment and configuration in such networks, firewall changes are +necessary. Firewall changes can be requested through a Service Now Change +Request or Change Task. diff --git a/admin-guide/operations.rst b/admin-guide/operations.rst new file mode 100644 index 00000000..797b5f81 --- /dev/null +++ b/admin-guide/operations.rst @@ -0,0 +1,9 @@ +Operations +========== + +.. toctree:: + :maxdepth: 2 + + operations/certificates + operations/deployment + operations/version-control diff --git a/admin-guide/operations/certificates.rst b/admin-guide/operations/certificates.rst new file mode 100644 index 00000000..d59fa350 --- /dev/null +++ b/admin-guide/operations/certificates.rst @@ -0,0 +1,68 @@ +Managing SSL certificates +========================= + +We use QuoVadis certificates from Switch. + + +Requesting certificates +----------------------- + +First create a certificate signing request (CSR) like this, replacing ``$FQDN`` +and ``$ALIASES``:: + + cat >$FQDN.cnf <`_. + +This procedure is described in more detail at the `SWITCH website +`_. + +SWITCH will send an email including instructions on how to download the +certificate. + + +Renewing certificates +--------------------- + +Using the same configuration file as above, generate a new private key and CSR, +and submit the CSR as before. + + +Revoke certificates +------------------- + +When receiving the first mail from SWITCH as described in `Requesting +certificates`_ one has to create an account to download the certificate. Using +this account, certificates can be revoked at the `QuoVadis website +`_. diff --git a/admin-guide/operations/deployment.rst b/admin-guide/operations/deployment.rst new file mode 100644 index 00000000..6a54f39b --- /dev/null +++ b/admin-guide/operations/deployment.rst @@ -0,0 +1,41 @@ +Deployment +========== + +This section describes how to (re-)deploy Puppet-managed Linux systems. The general process is: + +1. Register the system with sysdb (only for new systems). +2. Tell sysdb to perform an installation on the next boot. +3. Reboot the system and trigger a PXE boot (usually by pressing F12 during + POST). + +On some systems it is not possible to use PXE boot. Either because the network +card doesn't support it/has a bug/doesn't work with iPXE, or because the system +is in a network from which TFTP requests to the boot server are not allowed. In +those cases it is possible to either boot iPXE from a USB stick or DVD, or to +simply boot the RHEL installer from DVD and point it at the Kickstart file +generated by sysdb. + + +Registration with sysdb +~~~~~~~~~~~~~~~~~~~~~~~ + +The easiest way to interact with sysdb is to use bob, a command-line client +written in Python. Alternatively it is possible to use the web API directly. + +First, add the new node:: + + bob node add $FQDN $ENV local + + +To be able to PXE boot we need to configure at least one MAC address for the new +node:: + + bob node add-mac $FQDN 00:50:56:aa:fe:9b + + +Finally we need to configure the installer to use, and the Puppet-related +parameters:: + + bob node set-attr $FQDN ipxe_installer=rhel72server + bob node set-attr $FQDN puppet_env=prod + bob node set-attr $FQDN puppet_role=role::server diff --git a/admin-guide/operations/version-control.rst b/admin-guide/operations/version-control.rst new file mode 100644 index 00000000..a0eafb28 --- /dev/null +++ b/admin-guide/operations/version-control.rst @@ -0,0 +1,85 @@ +Version Control +=============== + + +Setting up Git +-------------- + +Initialize Git to use your username and PSI email address, for example:: + + git config --global user.name kaminski_k + git config --global user.email kai.kaminski@psi.ch + + +Gitlab server +------------- + +We use the `PSI-internal Gitlab server `_ to host our +repositories. + + +Groups +------ + +Currently, all of our repositories are in the repository group ``linux-infra``. + + +Setting up a repository +----------------------- + + +Repositories containing code are configured along the following lines: + +1. Only fast-forward merges are allowed, no merge commits. +2. Merge requests require at least one approval (by someone other than the + requester). + + +Workflow +-------- + +Changes to repositories containing **only** documentation can simply be pushed +to the repository in question. + +Changes to repositories containing code, SPEC files, or anything else that is +not pure documentation, need to be reviewed - even if the change in question +only changes documentation. + +To implement a change, follow these steps: + +1. Create an issue on GitLab. +2. Create a feature branch with name starting with + `issue-n-description`. +3. Assign the issue to yourself when you start working on it. +4. Commit the change to the feature branch and push it. +5. Create a merge request mentioning the issue in the commit message + or in the merge request (see `this + `_ for + the syntax). +6. Wait for **someone else** to approve and apply the merge request. + + +Commit messages +~~~~~~~~~~~~~~~ + +A commit message follows the well-known `50/72 format +`_: 50 +characters for the first line of the commit message, followed by a blank line, +which is then followed by zero or more paragraphs with a maximal line-length of +72 characters. + +If the commit fixes an issue recorded on Gitlab (which it should), the commit +message must start with ``Fix #N:``, where ``N`` is the number of the issue. +This will automatically close the issue when the commit is merged into master. + + +Code reviews +~~~~~~~~~~~~ + +During a code review be sure to check for at least the following: + +1. adherence to the guidelines described in this document,e.g. PEP8-compliance + for Python code +2. solid implementation: edge cases and failures are considered and handled + appropriately, etc. Non-obvious bits are explained. +3. documentation has been written or changed as appropriate diff --git a/admin-guide/puppet.rst b/admin-guide/puppet.rst new file mode 100644 index 00000000..30a0c21e --- /dev/null +++ b/admin-guide/puppet.rst @@ -0,0 +1,16 @@ +Puppet +====== + +Puppet documentation goes here. + +Contents: + +.. toctree:: + :maxdepth: 2 + + puppet/general + puppet/client + puppet/puppet-master + puppet/hiera + puppet/modules + puppet/development diff --git a/admin-guide/puppet/client.rst b/admin-guide/puppet/client.rst new file mode 100644 index 00000000..277cf5d5 --- /dev/null +++ b/admin-guide/puppet/client.rst @@ -0,0 +1,33 @@ +Puppet client +------------- + +Puppet client run is executed once daily between 5AM and 8AM +(``puppet_client::exec_time`` in hiera data). + +The puppet client is executed via the ``pli-puppet-run`` system timer: :: + + + [root@lxdev04 ~]# systemctl list-timers + NEXT LEFT LAST PASSED UNIT ACTIVATES + Wed 2017-10-25 15:55:54 CEST 6h left Tue 2017-10-24 15:55:54 CEST 17h ago systemd-tmpfiles-clean.timer systemd-tmpfiles-clean.service + Thu 2017-10-26 07:51:00 CEST 22h left Wed 2017-10-25 07:51:16 CEST 1h 5min ago pli-puppet-run.timer pli-puppet-run.service + + 2 timers listed. + Pass --all to see loaded but inactive timers, too. + +Puppet execution can be disabled for a certain amount of time with the +``/opt/pli/libexec/pli-puppet-disable`` command: :: + + [root@lxdev04 ~]# /opt/pli/libexec/pli-puppet-disable + puppet currently not disabled + [root@lxdev04 ~]# /opt/pli/libexec/pli-puppet-disable '1 week' + [root@lxdev04 ~]# /opt/pli/libexec/pli-puppet-disable + Puppet disabled until: Wed Nov 1 08:00:05 CET 2017 + [root@lxdev04 ~]# /opt/pli/libexec/pli-puppet-disable stop + Stopping + [root@lxdev04 ~]# /opt/pli/libexec/pli-puppet-disable + puppet currently not disabled + [root@lxdev04 ~]# + +The disabling time has to be in the ``date`` format (see date(1)). + diff --git a/admin-guide/puppet/components/grub2.rst b/admin-guide/puppet/components/grub2.rst new file mode 100644 index 00000000..6fc11ec9 --- /dev/null +++ b/admin-guide/puppet/components/grub2.rst @@ -0,0 +1,20 @@ +``grub2`` +========= + +This module provides a defined type to configure kernel arguments in grub2. + + +Defined Types +------------- + + +``grub2::kernel_arg`` +~~~~~~~~~~~~~~~~~~~~~ + +Modify a kernel argument. + +Parameters: + +- ``action``: one of 'add' and 'remove' +- ``value``: specifies the value for arguments of the form ``arg=value``, e.g. + ``crashkernel=auto``. diff --git a/admin-guide/puppet/components/logrotate.rst b/admin-guide/puppet/components/logrotate.rst new file mode 100644 index 00000000..3a679153 --- /dev/null +++ b/admin-guide/puppet/components/logrotate.rst @@ -0,0 +1,156 @@ +``logrotate`` +=========== + +This module configures ``logrotate``. Further information an examples can be +found in the following link: + +* https://git.psi.ch/linux-infra/voxpupuli-logrotate + +Main class ``logrotate`` can be called, but usually calling just a rule ``logrotate::rule`` +should be enough to automatically configure ``logrotate`` in the host. It will use the +default values for this class, which is placing all the default ``rules`` from the O.S. +to the ``/etc/logrotate.d`` directory. + +Parameters +---------- + +All available parameters are:: + + namevar - The String name of the rule. + path - The path String to the logfile(s) to be rotated. + ensure - The desired state of the logrotate rule as a String. Valid + values are 'absent' and 'present' (default: 'present'). + compress - A Boolean value specifying whether the rotated logs should + be compressed (optional). + compresscmd - The command String that should be executed to compress the + rotated logs (optional). + compressext - The extention String to be appended to the rotated log files + after they have been compressed (optional). + compressoptions - A String of command line options to be passed to the + compression program specified in `compresscmd` (optional). + copy - A Boolean specifying whether logrotate should just take a + copy of the log file and not touch the original (optional). + copytruncate - A Boolean specifying whether logrotate should truncate the + original log file after taking a copy (optional). + create - A Boolean specifying whether logrotate should create a new + log file immediately after rotation (optional). + create_mode - An octal mode String logrotate should apply to the newly + created log file if create => true (optional). + create_owner - A username String that logrotate should set the owner of the + newly created log file to if create => true (optional). + create_group - A String group name that logrotate should apply to the newly + created log file if create => true (optional). + dateext - A Boolean specifying whether rotated log files should be + archived by adding a date extension rather just a number + (optional). + dateformat - The format String to be used for `dateext` (optional). + Valid specifiers are '%Y', '%m', '%d' and '%s'. + dateyesterday - A Boolean specifying whether to use yesterday's date instead + of today's date to create the `dateext` extension (optional). + delaycompress - A Boolean specifying whether compression of the rotated + log file should be delayed until the next logrotate run + (optional). + extension - Log files with this extension String are allowed to keep it + after rotation (optional). + ifempty - A Boolean specifying whether the log file should be rotated + even if it is empty (optional). + mail - The email address String that logs that are about to be + rotated out of existence are emailed to (optional). + mailfirst - A Boolean that when used with `mail` has logrotate email the + just rotated file rather than the about to expire file + (optional). + maillast - A Boolean that when used with `mail` has logrotate email the + about to expire file rather than the just rotated file + (optional). + maxage - The Integer maximum number of days that a rotated log file + can stay on the system (optional). + minsize - The String minimum size a log file must be to be rotated, + but not before the scheduled rotation time (optional). + The default units are bytes, append k, M or G for kilobytes, + megabytes and gigabytes respectively. + maxsize - The String maximum size a log file may be to be rotated; + When maxsize is used, both the size and timestamp of a log + file are considered for rotation. + The default units are bytes, append k, M or G for kilobytes, + megabytes and gigabytes respectively. + missingok - A Boolean specifying whether logrotate should ignore missing + log files or issue an error (optional). + olddir - A String path to a directory that rotated logs should be + moved to (optional). + postrotate - A command String that should be executed by /bin/sh after + the log file is rotated (optional). + prerotate - A command String that should be executed by /bin/sh before + the log file is rotated and only if it will be rotated + (optional). + firstaction - A command String that should be executed by /bin/sh once + before all log files that match the wildcard pattern are + rotated (optional). + lastaction - A command String that should be execute by /bin/sh once + after all the log files that match the wildcard pattern are + rotated (optional). + rotate - The Integer number of rotated log files to keep on disk + (optional). + rotate_every - How often the log files should be rotated as a String. + Valid values are 'hour', 'day', 'week', 'month' and 'year' + (optional). Please note, older versions of logrotate do not + support yearly log rotation. + size - The String size a log file has to reach before it will be + rotated (optional). The default units are bytes, append k, + M or G for kilobytes, megabytes or gigabytes respectively. + sharedscripts - A Boolean specifying whether logrotate should run the + postrotate and prerotate scripts for each matching file or + just once (optional). + shred - A Boolean specifying whether logs should be deleted with + shred instead of unlink (optional). + shredcycles - The Integer number of times shred should overwrite log files + before unlinking them (optional). + start - The Integer number to be used as the base for the extensions + appended to the rotated log files (optional). + su_owner - A username String that logrotate should use to rotate a + log file set instead of using the default if + su => true (optional). + su_group - A String group name that logrotate should use to rotate a + log file set instead of using the default if + su => true (optional). + uncompresscmd - The String command to be used to uncompress log files + (optional). + +Examples +-------- + +Configure ``logrotate.conf``:: + + logrotate::conf { '/etc/logrotate.conf': + rotate => 10, + rotate_every => 'week', + ifempty => true, + dateext => true, + } + + +Rule for rotating ``messages``:: + + logrotate::rule { 'messages': + path => '/var/log/messages', + rotate => 5, + rotate_every => 'week', + postrotate => '/usr/bin/killall -HUP syslogd', + } + + +Rule for rotating ``slurmd`` client:: + + logrotate::rule { 'slurmd': + path => '/var/log/slurm/slurmd.log', + rotate => $rotate, + rotate_every => $rotate_every, + compress => true, + create => true, + create_mode => '0600', + create_owner => 'slurm', + create_group => 'slurm', + missingok => true, + ifempty => false, + sharedscripts => true, + postrotate => '/bin/systemctl reload slurmd.service > /dev/null 2>/dev/null || true'; + } diff --git a/admin-guide/puppet/components/selinux.rst b/admin-guide/puppet/components/selinux.rst new file mode 100644 index 00000000..a1157db5 --- /dev/null +++ b/admin-guide/puppet/components/selinux.rst @@ -0,0 +1,43 @@ +``selinux`` +=========== + +This module configures :doc:`/selinux`. It allows configuring the SELinux mode +as well as setting SELinux booleans. + + +Parameters +---------- + +``selinux_mode`` +~~~~~~~~~~~~~~~~ + +Acceptable values are ``enforcing``, ``permissive``, and ``disabled``. The +module configures this mode for the next reboot. It also sets it right away +unless the mode to be configured is ``disabled`` or SELinux is currently +disabled. In the former case the current mode is set to ``permissive``. In the +latter case nothing is done before the next reboot. + + +Defined Types +------------- + +``set_sebool`` +~~~~~~~~~~~~~~ + +Sets the SELinux boolean specified as the resource title unless SELinux is +disabled, in which case it does nothing. + +Parameters: + +- ``enable`` + + If true, the boolean is set to ``on``. If false, the boolean is set to + ``off``. + + +Examples +-------- + +Allow httpd to access user's home directories:: + + selinux::set_sebool {'httpd_enable_homedirs': enable => true } diff --git a/admin-guide/puppet/components/sudo.rst b/admin-guide/puppet/components/sudo.rst new file mode 100644 index 00000000..5d7fee7d --- /dev/null +++ b/admin-guide/puppet/components/sudo.rst @@ -0,0 +1,24 @@ +``sudo`` +======== + +This module installs and configures ``sudo(8)``. + +Parameters +---------- + + +``allow_sudoers_d`` +~~~~~~~~~~~~~~~~~~~ + +This boolean determines whether the files in ``/etc/sudoers.d/`` are included in +the sudo configuration. + + +Defined types +------------- + +``sudo::rules`` +~~~~~~~~~~~~~~~ + +This defined type accepts a parameter ``rules``, which is an array of strings to +be added to ``/etc/sudoers``. diff --git a/admin-guide/puppet/components/sysctl.rst b/admin-guide/puppet/components/sysctl.rst new file mode 100644 index 00000000..1deab796 --- /dev/null +++ b/admin-guide/puppet/components/sysctl.rst @@ -0,0 +1,18 @@ +``sysctl`` +=========== + +This module configures ``sysctl``. Further information an examples can be +found in the official page: + +* https://forge.puppet.com/tpdownes/sysctl + +The sysctl module is called automatically so is possible to do sysctl tuning +by configuring properly hiera using the `sysctl::values` variable, eg.:: + + sysctl::values: + net.ipv4.tcp_slow_start_after_idle: + value: '0' + net.core.rmem_max: + value: '83886080' + net.core.wmem_max: + value: '83886080' diff --git a/admin-guide/puppet/components/systemd.rst b/admin-guide/puppet/components/systemd.rst new file mode 100644 index 00000000..44f41b26 --- /dev/null +++ b/admin-guide/puppet/components/systemd.rst @@ -0,0 +1,77 @@ +``systemd`` +=========== + +This module provides defined types to create systemd units. It automatically +takes care of reloading systemd when necessary, automatically generates correct +names for ``.mount`` units, etc. + +The parameters of defined types are usually similar to the systemd option names +that they represent. Camel case (as used by systemd) is transformed to the +lowercase-with-underscore style usually used with Puppet, e.g. ``OnCalendar`` in +systemd becomes ``on_calendar``. + + +Parameters +---------- + +``default_target`` +~~~~~~~~~~~~~~~~~~ + +The systemd default target, i.e. usually one of ``multi-user.target`` or +``graphical.target``. + + +Defined Types +------------- + +All units support the following parameters for the ``[Unit]`` or ``[Install]`` +sections: + +- ``description`` +- ``wanted_by`` + + +``systemd::timer`` +~~~~~~~~~~~~~~~~~~ + +Creates a timer unit. + +Parameters: + +- ``on_calendar`` +- ``unit`` + + +``systemd::mount`` +~~~~~~~~~~~~~~~~~~ + +Creates a mount unit. The name of the unit file has to be (an encoded form of) +the mountpoint, which is automatically generated. See ``systemd.mount(5)`` for +details. + +Parameters: + +- ``what`` +- ``where`` +- ``options`` + + +``systemd.service`` +~~~~~~~~~~~~~~~~~~~ + +- ``type`` (default: ``simple``) +- ``exec_start`` + + +Examples +-------- + +Defining a timer unit +~~~~~~~~~~~~~~~~~~~~~ + +Timer units integrate nicely with the remaining services. They can be managed +through ``systemctl(1)`` and their log messages can easily be accessed through +``journalctl -u xxxxx.timer``. + +A timer unit needs a corresponding service unit which executes the actual +command. diff --git a/admin-guide/puppet/components/updatedb.rst b/admin-guide/puppet/components/updatedb.rst new file mode 100644 index 00000000..a1182efc --- /dev/null +++ b/admin-guide/puppet/components/updatedb.rst @@ -0,0 +1,24 @@ +``updatedb`` +============ + +This module manages the configuration for ``mlocate`` aka ``updatedb(8)``. + + +Parameters +---------- + +``enable`` +~~~~~~~~~~ + +A boolean indicating whether ``mlocate`` - ie the ``updatedb(8)`` cron job - +should be enabled or not. + + +Defined Types +------------- + +``updatedb::exclude`` +~~~~~~~~~~~~~~~~~~~~~ + +Takes a list of directories and makes sure that ``updatedb(8)`` ignores them +when indexing. diff --git a/admin-guide/puppet/components/utils.rst b/admin-guide/puppet/components/utils.rst new file mode 100644 index 00000000..eb2a6d28 --- /dev/null +++ b/admin-guide/puppet/components/utils.rst @@ -0,0 +1,32 @@ +``utils`` +========= + +This module contains a number of utility functions used at PSI. It is the +PSI-specific analogue to Puppetlabs' ``stdlib``. + + +Functions +--------- + + +``check_os`` +~~~~~~~~~~~~ + +Accepts an arbitrary number of arguments, each of which is a string of the form +``$osfamily $majorversion`` as reported by ``facter(8)``. If the facts of the +client system **do not** match any of the arguments, the function aborts the +Puppet run. + + +``rand_time`` +~~~~~~~~~~~~~ + +This function takes a parameter specifying a time window and returns a specific +time within this window based on the MD5 on the hostname. This allows scheduling +cron jobs etc uniformly across a fleet of system within a given window, while +keeping the time on each system predictable. + +The format for the argument specifying the time window is ``HH:MM--HH:MM``. The +window must not include midnight. + +The format of the return value is ``HH:MM``. diff --git a/admin-guide/puppet/development.rst b/admin-guide/puppet/development.rst new file mode 100644 index 00000000..8edc574d --- /dev/null +++ b/admin-guide/puppet/development.rst @@ -0,0 +1,52 @@ +Development Environments +======================== + +The puppet server gives access to a limited set of users to the +environment area, where prod and preprod environments are already +present, to create environments that can be used for new puppet code +development. + +This area is accessible via sftp and can be mounted on users' +workstations via sshfs. + +The typical workflow would be: + + #. user mounts the environment area (``puppet00:/envs`` on the puppet master) via sshfs on ``~/puppetenv``; + #. user create a directory for the new environent (``mkdir ~/puppetenv/issue_x``); + #. after a few seconds ``issue_x`` will be populated with a copy of the content of the the ``preprod`` environment with a proper git branch named ``issue_x``; + #. user edits files in that directory; + #. user run on some testing node the command ``puppet agent -t --environment=issue_x``; + #. user iterates on steps number 4 and 5 until the code is ready; + #. users makes the proper add/commit into the directory and finally pushes the code; + #. from the git server web interface user triggers a merge request of the ``issue_x`` into the ``preprod`` branch. + +Please note that ssh to the puppet server has to be done via ``wmgt`` nodes. + +Environment names +----------------- + +The name of the environment: + + - must be at least 4 characters long; + - can include lower case letters, digits and the underscore character; + - must start with a letter. + +If the name is not compliant with these rules, the directory will be automatically removed. + +SSHFS mount +----------- + +Generally refer to your operating system instructions on how to +properly configure sshfs. + +One caveat is that your local user can be different from the remote (puppet master) +user. In this case a file mapping your local username to the remote user id should be passed to the sshfs client. +The file should be in the form of:: + + : + +And should then be passed in the command like:: + + sshfs -o idmap=file,uidfile=/Users/talamoig/uidmap,nomap=ignore talamo_i@puppet00:/ ~/puppetenvs + + diff --git a/admin-guide/puppet/general.rst b/admin-guide/puppet/general.rst new file mode 100644 index 00000000..bd897a1a --- /dev/null +++ b/admin-guide/puppet/general.rst @@ -0,0 +1,96 @@ +General +======= + +`Puppet `_ is the *configuration management system* used to configure the hosts. + +Introduction +------------ + +Puppet is used in master mode and the general idea is to make large +use of indipendent and (relatively) small puppet +modules and composing profiles and roles based on them to create +classes that are assigned to the hosts. With indipendence +of puppet modules we mean that each puppet module targets a single +functionality (eg. `web server`, `afs client`) and this +is choosen to keep the code of the single module smaller, more +coherent and easier to debug. + +Furthermore the system makes use of some puppet modules from the `puppet forge +`_. These puppet modules are not accessed directly but +through their PSI mirror, inside of the `Linux-infra group `_. + +Code and data are kept separated, using puppet modules +for code and hiera for data. Secure data are safely managed +inside hiera using `hiera eyaml `_. + +To each host the following element will determine how it will be configured: + +- the puppet environment (that will determine the puppet role/profile code base) +- the sysdb data environment (that will determine the hiera code base) +- the puppet group (that will determine what files will be considered in the hiera code base) +- the role + +All these elements are configured inside sysdb as attributes and are accessed +by the puppet master via the ENC. + +Here you can get a general overview: + +.. following image generated from https://docs.google.com/drawings/d/16AXZd5PF-HgW379Cxgvwzvc6MTl_34LVFHzP5Fi8RdQ/edit + +.. image:: puppet_workflow.jpg + + + +Environments +------------ + +We use Puppet environments for two purposes: + +- roll out changes to a small subset of all systems first +- module development + + +The following environments exist: + +- ``prod`` + + The most stable, and most systems are attached to it. All changes to ``prod`` + have to go through ``preprod`` first. + +- ``preprod`` + +- Development environments. These are private to a single developer, + can have arbitrary names like ``ganglia-issue-21`` or + ``kaminski_k-log_client``, and are used for developing and testing + changes. Generally, only individual systems are attached to these + environments. + + + +puppet master +------------- + +The puppet master will make use of the `ENC +`_ for getting +two informations: + + - the environment; + - the role. + +The environment is used to determine the directory location inside +`/etc/puppetlabs/code/environments` where to look code for. + +The role is a class-name inside the specific environment that will be +used to generate the node catalog. + +Assuming for example the following result from the ENC for a specific node: :: + + --- + environment: production + classes: + - role::log_server + +the puppet master will look for the a puppet class named +``role::log_server`` in the file +`/etc/puppetlabs/code/environments/productions/modules/psi/manifests/role/log_server.pp`. + diff --git a/admin-guide/puppet/hiera.rst b/admin-guide/puppet/hiera.rst new file mode 100644 index 00000000..733be349 --- /dev/null +++ b/admin-guide/puppet/hiera.rst @@ -0,0 +1,201 @@ +Hiera +===== + +Look `here `_ for a general Hiera +introduction. + +The current hierarchy has four levels (first will be considered first +during value lookup): + +- nodes (FQDN) +- group (``puppet_group`` attribute in sysdb) +- sysdb environments +- common + +and values can be stored as classical YAML values or with `encrypted yaml +`_ for secrets. +The filesystem structure is as follows:: + +1. ``%{::sysdb_env}/%{::group}/%{::fqdn}`` +2. ``%{::sysdb_env}/%{::group}`` +3. ``%{::sysdb_env}/%{::sysdb_env}`` +4. ``%{::environment}/data/common`` + +The ``%{variable}`` notation is hiera specific and each path represents a ``.yaml`` +file. + +Hiera repositories +------------------ + +Hiera data are organized in different repositories. + +Sysdb environments data +^^^^^^^^^^^^^^^^^^^^^^^ + +Each sysdb environment has a dedicated hiera repository, called ``data-``, +eg. `data-hpc `_ +and `data-sls `_. +The first three levels of the filesystem structure shown before are actually the +files inside this kind of repositories. + +Any change to the repo will automatically trigger a redeployment of the new version +of its content on the puppet master within a few seconds from the push. + +This choice has been made to allow groups to change their hiera data independently of +the linux infrastructure admins. Furthermore there is no way to influence other sysdb +environments data. + +Common data +^^^^^^^^^^^ + +The last element in the hierarchy (``common.yaml``) is instead defined inside the main puppet repository +(the one containing also the real puppet code). It is important to notice that the version +of the ``common.yaml`` used for a specific host will depend on the puppet environment it +is running on, while for the sysdb environements data are the same, whatever the puppet +environment of the host. + +The common part is kept under the control of the linux infrastructure admins +since a change on this can have an impact on a much larger set of hosts and all the changes +on this file are discussed and approved through a longer process. + +Example +------- + +Assuming two sysdb environments ``hpc`` and ``sls``, as well as: + +- group ``merlin4`` in ``hpc`` with ``merlinc10`` and ``merlinc11`` in it; +- group ``merlin5`` in ``hpc`` with ``merlin-c001`` and ``merlin-c002`` in it; +- group ``mx`` in ``sls`` with ``mxcn-1`` and ``mxcn-2`` in it; +- host ``xbl-gateway`` in no explicit group (will take the implicit ``default``) + +the Hiera structure would look like this:: + + data/hpc/merlin4/merlinc10.psi.ch.yaml + data/hpc/merlin4/merlinc11.psi.ch.yaml + data/hpc/merlin4.yaml + data/hpc/merlin5/merlin-c001.psi.ch.yaml + data/hpc/merlin5/merlin-c002.psi.ch.yaml + data/hpc/merlin5.yaml + data/hpc.yaml + data/sls/mx/mxcn-1.psi.ch.yaml + data/sls/mx/mxcn-2.psi.ch.yaml + data/sls/mx.yaml + data/sls/default/xbl-gateway.psi.ch.yaml + data/sls.yaml + code/environments/{prod,preprod}/common.yaml + +While the output of bob would be something like (some unneeded attributes have been removed):: + + merlinc10.psi.ch hpc local puppet_group=merlin4 + merlinc11.psi.ch hpc local puppet_group=merlin4 + merlin-c001.psi.ch hpc local puppet_group=merlin5 + merlin-c002.psi.ch hpc local puppet_group=merlin5 + mxcn-1.psi.ch sls local puppet_group=mx + mxcn-2.psi.ch sls local puppet_group=mx + xbl-gateway.psi.ch sls local + +Secret values +------------- + +Secrets and clear-text values can be mixed inside the same yaml file, eg.:: + + ntp_client::servers: + - pstime1.psi.ch + - pstime2.psi.ch + - pstime3.psi.ch + + secret_key: ENC[PKCS7,MIIBiQYJKoZIhvcNAQcDoIIBejCCAXYCAQAxggEhMIIBHQIBADAFMAACAQEwDQYJKoZIhvcNAQEBBQAEggEAY/9V1S0VAMrRX1B4V06AgsbHPHdONFCQ4RiWfTrhV02rL5gSL4LAdqOuvGPY8YZZv8Mp06/FARlvP1aOfEx7avqSBy11IoUGkeajKZFzJV3OJsfhso4wroQ4JmfBaVKICnQZwCdpke+PHPRkwTgHcjmY2FeBnhvOlrGiQMQU3JzCjLePOa7UvlIIin3xOU/TdetzhfvoNGRhsz7+XRPD+mTT8efJ+OslJmqU7hEqMbs9CmhPJWqsjsQUp8jsM10Dk2Rv4v+zYeJd1ZLRGK3Z56G4NrlLyYua+/yyPbUP4+1bEuisDg9bfQHp3R491/kN0W558oQ+85rsRVXCp1Hb6TBMBgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBB2x9awGQnxAJsxIHA9OiM2gCBFvgxIR4SJZPrrQ/UlhKU39yYSkEmuKE/ou+yeIe5AMA==] + + +The encrypted values can be decrypted transparently from Hiera (on a host having the proper hiera key):: + + [root]# hiera secret_key + this is a secret value + +You can edit secure data inside any yaml file with the command +``/opt/puppetlabs/puppet/bin/eyaml edit common.yaml``. In this case secure data +will appear in clear-text inside the editor. + + +Encripting data with the public key +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The eyaml public key is:: + + -----BEGIN CERTIFICATE----- + MIIC2TCCAcGgAwIBAgIBATANBgkqhkiG9w0BAQUFADAAMCAXDTE2MTAyNDE0NTY1 + N1oYDzIwNjYxMDEyMTQ1NjU3WjAAMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB + CgKCAQEA2eykSgS7VJEXrWYkQMV48ZkUVcHMbCEo2gZXD4vIJsOdJu77F7tA53Ay + NxdKnJTftsj+R7yFP9Z2XllA9Our0Ypphj40rNstRg5O4IoSkAqitJchlfGL9jZ3 + CB4dJqFitzOkxxCWZjQpjBd3dMJc6U3us6IDWohCjYqyjMZIVwU5EflzJKV4haEy + Y9qHkVt938RM9UohEvia5/1lZxuZQmDpYqCw9gmBK/dVKZ7abZGkujTKAg5cjD/X + vuexLMCGrjnPdrsblwBh+yfu6cEo9nfvfj6EA0FxPHIvQ3fv1yJZ+90OA9eUJnqQ + ED66OGPATAJIqhWlgb8a760xPQFQQQIDAQABo1wwWjAPBgNVHRMBAf8EBTADAQH/ + MB0GA1UdDgQWBBSF05r9TYDiAmkdguCVcDzmYR8Q6TAoBgNVHSMEITAfgBSF05r9 + TYDiAmkdguCVcDzmYR8Q6aEEpAIwAIIBATANBgkqhkiG9w0BAQUFAAOCAQEAWAER + CTGsOFUkCfvqke75PmIkxKBp/2eJbavWzPkbA/mwAGS4lQc5oyS8FMkUFxATo1k/ + WIb2B3WJIMHfCzMNxTlQLjJiSyvWAlEBHDW4H2XekzKSbj96l+/nirmOq3QkEKTK + omexF5zYSPkBVA/S2m2wae3g2kubH1p42+REKQUvt1+xaecHBYD6eXzBWChnMMnq + FbXoayTibn0p9Roo8HClGGJpjPZUTMf+VGUqKWPfvaKl48Y0yrc/4BzZT6Sbzeou + ZSiHwa62rTV7ia7m2SILZU5b65JUVkFH/2r6qkxCr0Ep+oaxSNXtAXLCbnXmdOeK + B40J8ePbbmmGE24+zQ== + -----END CERTIFICATE----- + + +Assuming the public key is saved in a file named ``/home/someone/eyaml_key.pub`` and that +`hiera-eyaml `_ is properly installed, +a string can be encripted with:: + + eyaml encrypt --pkcs7-public-key=/home/someone/eyaml_key.pub -s secret_string + + +While a complete file can be encripted with:: + + eyaml encrypt --pkcs7-public-key=/home/someone/eyaml_key.pub -f secret_file + +Example: Encripting password +---------------------------- + +Steps: + +Install locally (local = server/desktop from where you will encrypt the password) hiera-eyaml (https://github.com/voxpupuli/hiera-eyaml/tree/command-refactor) + +Create locally a *keys* directory:: + + #> mkdir -p ~/eyaml/keys + +Copy *puppet00:/etc/puppetlabs/keys/eyaml/public_key.pkcs7.pem* to the above folder. Alternatively, you can copy the above public key, which should be the same:: + + #> scp root@puppet00:/etc/puppetlabs/keys/eyaml/public_key.pkcs7.pem ~/eyaml/keys + +Go to the *eyaml* directory:: + + #> cd ~/eyaml + +Hash your password using *openssl* as follows**. It will generate a hashed password:: + + #> openssl passwd -1 + Password: + Verifying - Password: + + +Encrypt your hashed password with *eyaml* and copy the exact output (either the string or the block) to your hiera (YAML) file:: + + #> eyaml encrypt -l 'root::password' -s '' + root::password: ENC[PKCS7,MIIBmxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + + OR + + root::password: > + ENC[PKCS7,MIIBmxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx + xxx] diff --git a/admin-guide/puppet/modules.rst b/admin-guide/puppet/modules.rst new file mode 100644 index 00000000..65eb2f00 --- /dev/null +++ b/admin-guide/puppet/modules.rst @@ -0,0 +1,259 @@ +Modules +======= + +The repository for the Puppet role/profile module is +``_. + +The general roles structure is:: + + role::generic_server + role::generic_desktop + ... + role::daas::compute + role::daas::login + ... + role::sls::console + role::sls::boot_server + +So we have some roles that are generic PSI-wide (eg. ``generic_server``) while +some roles that are specific to some projects and have a dedicated namespace. + +For the profiles section we have the following:: + + profile::ssh_client + profile::afs_client + profile::log_client + profile::mysql_server + +For profiles maybe we will not need namespace areas dedicated to +specific projects, since profiles should be generic enough to be +reusable. + + +How to write modules +-------------------- + +The structure of a module depends on the type of module to some extent. +Currently, we distinguish three kinds of modules: + +- roles +- profiles +- components + + +Parameter validation +~~~~~~~~~~~~~~~~~~~~ + +The first thing every module must do is parameter and environment validation. In +particular, a module should check that + +- its arguments have the correct type +- it supports the OS of the client system + +A typical module could start like this:: + + class profile::logging ( + $forward_to, + $persistent_journal, + ) + { + validate_array($forward_to) + validate_bool($target) + + check_os('RedHat 7', 'RedHat 8') + } + +This would make sure that ``$forward_to`` is an array, ``$persistent_journal`` +is a boolean, and that the client runs RHEL 7 or (a hypothetical) RHEL 8. + +Arguments should be checked first, in the order that they are passed. + +Checking the OS will ease porting efforts to newer releases of RHEL, other +distributions (e.g. Ubuntu), or other operating systems (e.g. BSD), should the +need arise. + + +Hiera queries +~~~~~~~~~~~~~ + +Only profiles and roles query Hiera. Components should take all their inputs as +parameters or facts. + +In profiles, Hiera queries must generally be done as default arguments to +parameters, **not** inside the modules body:: + + class profile::logging ( + $forward_to=hiera('...'), + $persistent_journal=hiera('...'), + ) + { + +The reason is that this allows a role to enforce certain parameters and disable +the corresponding Hiera query. + + +Layout +~~~~~~ + +Roles and profiles are usually implemented in a single file, e.g. +``psi/manifests/profile/logging.pp``. Components on the other hand follow the +standard Puppet layout, i.e. +``auditd/manifests/{init,install,config,service}.pp``. + +Files and templates +~~~~~~~~~~~~~~~~~~~ + +Every file or template should be used by only one class and its path inside the +module should reflect this. Eg. if the template ``sshd_config.erb`` is used by +the ``profile::ssh_server`` module, it will be places inside the +``templates/profile/ssh_server`` directory. + +Furthermore, on top of every file managed by puppet, a header like the +following should be present: :: + + ######################################################################## + # + # THIS FILE IS MANAGED BY PUPPET - DO NOT MODIFY! + # + # profile::ssh_server + # sshd_config.erb + # + ######################################################################## + +The last two lines should be: + + - the puppet class using the file; + - the name of the file/template. + +Debugging templates +~~~~~~~~~~~~~~~~~~~ + +You can use the ``erb`` tool to test the variable interpolation. One easy way is to prepare a file with the variable values and pipe it together with the template through erb. Define the variables in a file ``test-vars.erb`` like in this example:: + + <% + @partitions = {'a' => 'aa', 'b' => 'bb', 'c' => 'cc'} + @group_whitelist = ['groupA', 'groupB'] + @port = 8000 + %> + +and then use a commmand line like the following to pipe it through ``erb``:: + + erb <(cat /tmp/test-vars.erb /tmp/my-template.erb) + +The output will contain the variable substituted template. If you want to check your +template for syntax errors, you can just use the following command:: + + erb -P -x -T '-' jupyterhub_config.py.erb | ruby -c + +Roles +----- + +.. toctree:: + :maxdepth: 1 + + roles/base + roles/bootpc + roles/console + roles/daq_buffer + roles/dcache_t3_pools + roles/desktop + roles/ganglia_server + roles/grafana + roles/hpc/ces + roles/hpc/cn + roles/hpc/database + roles/hpc/ui + roles/hpc/server + roles/influxdb + roles/jupyterserver + roles/log_server + roles/login_server + roles/media_station + roles/nomachine_proxy + roles/reverse_proxy + roles/server + roles/slurm_client + roles/slurm_compute + roles/slurm_server + roles/softioc + roles/web_server + roles/workstation + roles/zookeeper + + +Profiles +-------- + +.. toctree:: + :maxdepth: 1 + + profiles/aaa + profiles/afs_client + profiles/autofs + profiles/custom_timers + profiles/epics + profiles/filecopy + profiles/files + profiles/ganglia_client + profiles/ganglia_server + profiles/gnome + profiles/gpfs + profiles/grafana + profiles/icewm + profiles/icinga/client + profiles/icinga/nrpe + profiles/icinga/checks/gpfs + profiles/icinga/checks/nvidia + profiles/icinga/checks/puppet_client + profiles/icinga/checks/service + profiles/icinga/checks/slurm + profiles/icinga/checks/hp/smart_array + profiles/infiniband + profiles/jupyterhub + profiles/kdump_client + profiles/local_accounts + profiles/log_client + profiles/log_server + profiles/mkresource/files + profiles/mounter + profiles/mta + profiles/multipath + profiles/nomachine + profiles/nomachine/desktop + profiles/nomachine/license + profiles/nomachine/repository + profiles/nomachine/service + profiles/nomachine/terminal + profiles/nomachine/workstation + profiles/networking + profiles/nfs_server + profiles/ntp_client + profiles/nvidia + profiles/platform + profiles/platform/hewlett_packard + profiles/pmodules + profiles/print_client + profiles/puppet_client + profiles/serial_console + profiles/ssh_client + profiles/ssh_server.rst + profiles/sysinfo + profiles/telegraf + profiles/web_server + profiles/yum_client + + +Components +---------- + +.. toctree:: + :maxdepth: 1 + + components/grub2 + components/logrotate + components/selinux + components/sudo + components/systemd + components/sysctl + components/updatedb + components/utils diff --git a/admin-guide/puppet/profiles/aaa.rst b/admin-guide/puppet/profiles/aaa.rst new file mode 100644 index 00000000..33f99899 --- /dev/null +++ b/admin-guide/puppet/profiles/aaa.rst @@ -0,0 +1,336 @@ +``profile::aaa`` +===================== + +This module manages configuration related to authentication, authorization, and +auditing. In particular, it + +- performs the Active Directory join (optional) +- configures login restrictions (e.g. :manpage:`pam_access(8)`) +- adds sudo rules for administrators + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +admins list hiera_array('aaa::admins') +allow_sudoers_d bool hiera('aaa::allow_sudoers_d') +bastions list hiera('aaa::bastions') +cache_creds bool hiera('aaa::cache_creds') +create_homes bool hiera('aaa::create_homes') +enable_ad bool hiera('aaa::enable_ad') +enable_eaccounts bool hiera('aaa::enable_eaccounts') +enable_slurm bool false +enable_ssh_allow bool hiera('aaa::enable_ssh_allow') +enable_tier3_ldap bool hiera('aaa::enable_tier3_ldap', false) +ldap_enabled bool hiera('aaa::ldap_enabled') +offline_creds_expiration string hiera('aaa::offline_creds_expiration') +override_homedir string hiera('aaa::override_homedir', undef) +ssh_authorized_keys hash hiera_hash('aaa::sshkeys', {}) +sssd_debuglevel int hiera('aaa::sssd_debuglevel') +sudo_rules (Hiera only) list hiera_array('aaa::sudo_rules', []) +support_afs bool hiera('aaa::support_afs'), +use_bastions bool hiera('aaa::use_bastions', undef) +users list hiera_array('aaa::users', []) +=============================== ======== ================================================ + + +``admins`` +~~~~~~~~~~ + +A list of user and/or group names. The users as well as the members of the groups +can log in on the system and have full root privileges via sudo. + +Group names must be prefixed with ``%``. + +Example:: + + aaa::admins: + - 'markushin' + - 'gsell' + - 'barabas' + - '%unx-linux_support' + +Also see `users`_. + + +``allow_sudoers_d`` +~~~~~~~~~~~~~~~~~~~ + +This boolean controls whether the files in ``/etc/sudoers.d`` are taken +into account by sudo. + + +``bastions`` +~~~~~~~~~~~~ + +A list of FQDNs. If `use_bastions`_ is true, then root logins are only allowed +from the hosts on this list. *Note*: If the list is empty, login is unrestricted +again! + +Example:: + + aaa::bastions: + - 'gpfs-node1.psi.ch' + - 'gpfs-node2.psi.ch' + - 'gpfs-node3.psi.ch' + - 'wmgt01.psi.ch' + - 'wmgt02.psi.ch' + +``create_homes`` +~~~~~~~~~~~~~~~~ + +This boolean controls whether home directories are created on login when +necessary. This only works if the underlying filesystem allows it. In +particular, it does not work on AFS. + +Also see `override_homedir`_. + + +``cache_creds`` +~~~~~~~~~~~~~~~~~~~~~ + +This boolean controls whether sssd caches credentials. + +Also see `offline_creds_expiration`_. + + +``enable_ad`` +~~~~~~~~~~~~~ + +Determines whether the system will be configured for Active Directory +authentication. + + +``enable_eaccounts`` +~~~~~~~~~~~~~~~~~~~~ + +Setting this to ``true`` enables the Active Directory OU containing the +e-accounts. + + +``enable_slurm`` +~~~~~~~~~~~~~~~~ +When set to ``true``, we allow slurm users to login on computing nodes in where +their jobs are running. Otherwise, users are not allowed to login in the computing +nodes. + +To enable this behaviour, someone needs to call directly the ``profile::aaa`` class +and enable this feature, but also needs to change the call of the ``role::base`` +class by setting ``include_aaa`` to ``false``. For example:: + + class { + 'role::base': + include_aaa => false; + 'profile::aaa': + support_afs => hiera('base::enable_afs'), + enable_slurm => true; + 'slurm::compute': + cluster => $cluster; + } + + + +``enable_ssh_allow`` +~~~~~~~~~~~~~~~~~~~~ + +Allow users to manage access to the system bypassing Puppet by adding usernames +to ``/etc/security/ssh.allow.user``. This file is never touched by Puppet. +Documentation can be found in :manpage:`pam_listfile(8)` or +``/etc/security/ssh.allow.README`` on the target system. + + +``enable_tier3_ldap`` +~~~~~~~~~~~~~~~~~~~~~ +When set to ``true``, sssd.conf is configured to support only OpenLDAP for +the Tier3. Other domains (Active Directory D.PSI.CH and LDAP SLS.PSI.CH) are +not included in the configuration file. + + +``ldap_enabled`` +~~~~~~~~~~~~~~~~ + +This boolean controls whether LDAP (AD) is used for user information and +authentication. + +In this case the following port have to be accessible from the host to the +domain controllers: + + - 389/TCP + - 389/UDP + - 88/TCP + - 88/UDP + - 464/UDP + + + +``offline_creds_expiration`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This integer controls for how many days cached credentials are valid after the +last successful online login. A value of 0 means that there is no limit. + +Also see `cache_creds`_. + + +``override_homedir`` +~~~~~~~~~~~~~~~~~~~~ + +This string defines the home directory path to use as expected by sssd's +``override_homedir`` option. See :manpage:`sssd.conf(5)` for details. + +Example:: + + aaa::override_homedir: '/home/%u' + + +``sshkeys`` +~~~~~~~~~~~ + +A hash of hashes, each of which contains the parameters as accepted by the +`ssh_authorized_key +`_ resource +type. + +Example:: + + aaa::sshkeys: + 'root@ra': + user: 'root' + type: 'ssh-dss' + key: 'AAAAB3Nz...' + +Keep in mind that this only works if the user's home directory is accessible to +root. In particular, it doesn't work if the home is on AFS. + + +``sssd_debuglevel`` +~~~~~~~~~~~~~~~~~~~ + +This integer configures sssd's ``debug_level`` option (see +:manpage:`sssd.conf(5)`). It is rarely necessary to use this setting, as the +debug level can be changed at runtime using :manpage:`sss_debuglevel(8)`. + + +``sudo_rules`` +~~~~~~~~~~~~~~ + +A list of strings taken from Hiera containing additional sudo rules. + + +``support_afs`` +~~~~~~~~~~~~~~~ + +Configure PAM and related tools which are necessary for running AFS. + + +``use_bastions`` +~~~~~~~~~~~~~~~~ + +This parameter determines whether root logins are only possible from the hosts +listed in `bastions`_. Normally the value is taken from the network property of +the same name, but this parameter allows overriding the network setting through +Hiera or in Puppet manifests. + + +``users`` +~~~~~~~~~ + +A list of user and/or group names. The users as well as the members of the +groups can log in on the system. + +Group names must be prefixed with ``%``. + +Also see `admins`_. + + +``ssh_authorized_key`` +~~~~~~~~~~~~~~~~~~~~~~ + +A hash containing SSH public keys as expected by the ``ssh_authorized_key`` +Puppet resource. + + +Examples +-------- + +The base role includes this profile by default. If you need to customize the +profile, do it like this:: + + class role::some_role () { + class {'role::base': + include_aaa => false, + ... + } + + class {'profile::aaa': + override_homedir => '/localhomes/%u', + create_homes => true, + ... + } + ... + + +Implementation Notes +-------------------- + + +User/Group Enumeration +~~~~~~~~~~~~~~~~~~~~~~ + +User/group enumeration happens when using the ``{set,get,end}pwent`` and +``{set,get,ent}grent`` APIs to enumerate all users or groups. These are used by +``getent passwd`` and ``gentent group`` for example, when not providing a +specific user or group to query. + +Enumeration would potentially be very slow and put a high load on the AD domain +controllers if it were to return all users/groups from AD. To prevent this, we +disable enumeration for AD accounts using the ``enumerate`` setting in +:manpage:`sssd.conf(5)`. This means that enumeration using the APIs/programs +above only returns local users and groups. + + +The ``min_id`` issue +~~~~~~~~~~~~~~~~~~~~ + +There are Unix groups in AD at PSI with very low GIDs, the lowest being 101 +(``unx-fkt``). This leads to problems, because :manpage:`sssd(8)` ignores users +and groups with GIDs lower than ``min_id`` (from :manpage:`sssd.conf(5)`), which +has a value of 500 by default. + +Therefore we set ``min_id`` to 100. One consequence is that there is overlap +between the IDs considered by sssd when querying AD, and the ID range for system +users and groups (``[SYS_]ID_{MIN,MAX}``) as defined in +:manpage:`login.defs(5)`. + +When creating system groups, :manpage:`groupadd` scans **all** GIDs from +``SYS_GID_MAX`` to ``SYS_GID_MIN``. This causes a number of requests to AD, +which is usually not a problem but can be, if those take a long time to +complete. This used to happen without the ``ad_enabled_domains`` setting for +example. ``sssd`` would query ``d.ethz.ch`` in addition to ``d.psi.ch``, which +would time out after a few seconds. + + +PAM details +~~~~~~~~~~~ + +There have been discussions to move :manpage:`pam_access` to the ``auth`` +section (from the ``account`` section) to prevent information leakage for +accounts that can't even log in: an attacker would get a different error message +depending on whether the password was wrong or whether :manpage:`pam_access` +didn't allow access. + +The problem is that when using Kerberos authentication, sshd does not use PAM +for authentication, circumventing :manpage:`pam_access`. Hence, just moving the +latter from ``account`` to ``auth`` does not work. + + +Kerberos ticket/AFS token renewal +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Kerberos tickets and AFS tokens are automatically renewed for as long as +possible. This is done by running a :manpage:`krenew` for every session in the +background. + diff --git a/admin-guide/puppet/profiles/afs_client.rst b/admin-guide/puppet/profiles/afs_client.rst new file mode 100644 index 00000000..efbcd21a --- /dev/null +++ b/admin-guide/puppet/profiles/afs_client.rst @@ -0,0 +1,51 @@ +``profile::afs_client`` +============================ + +This module installs and configures the OpenAFS client. + +On systems using AFS it is necessary to have the AFS kernel module for the +running kernel installed. This module installs the AFS kernel module for +**every** installed kernel (usually up to 3). Therefore it is recommended to run +Puppet after (kernel) updates. + +Note: Simply including this profile is usually **not** enough to enable AFS on a +system. It is also necessary to enable AFS support when including +``profile::aaa``. The latter makes sure that AD is used for authentication and +configures PAM to automatically create and renew AFS tokens. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +enable_dynroot bool hiera('afs_client::enable_dynroot') +min_cache_size int hiera('afs_client::min_cache_size') +mountpoint string hiera('afs_client::mountpoint') +root_volume string hiera('afs_client::root_volume') +=============================== ======== ================================================ + + +``enable_dynroot`` +~~~~~~~~~~~~~~~~~~ + + +``min_cache_size`` +~~~~~~~~~~~~~~~~~~ + +The minimum size for the local AFS cache. If the cache is smaller than this, +Puppet will try to resize the logical volume =lv_openafs=, otherwise Puppet will +leave it alone. + + +``mountpoint`` +~~~~~~~~~~~~~~ + +Defines the mountpoint for the AFS filesystem. + + +``root_volume`` +~~~~~~~~~~~~~~~ + +The name of the root volume to mount. diff --git a/admin-guide/puppet/profiles/autofs.rst b/admin-guide/puppet/profiles/autofs.rst new file mode 100644 index 00000000..c3df6998 --- /dev/null +++ b/admin-guide/puppet/profiles/autofs.rst @@ -0,0 +1,23 @@ +``profile::autofs`` +=================== + +This profile enables the ``autofs`` service. For normal automounts this is not +necessary, as they can be implemented using systemd, but this module can enable +the autofs ``-hosts`` map. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +install_auto_master bool hiera('autofs::install_auto_master', true) +=============================== ======== ================================================ + + +``autofs::install_auto_master`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If this variable is true, the profile will create an ``/etc/auto.master`` file +enabling the ``-hosts`` map on ``/net``. diff --git a/admin-guide/puppet/profiles/custom_timers.rst b/admin-guide/puppet/profiles/custom_timers.rst new file mode 100644 index 00000000..90e280cf --- /dev/null +++ b/admin-guide/puppet/profiles/custom_timers.rst @@ -0,0 +1,40 @@ +``profile::custom_timers`` +========================== + +This profile is a defined type to define systemd timers together with the corresponding service. + +The resources are defined using the ``systemd::service`` and ``system::service``. +The service is defined as type simple and it it has dependency (``Wants`` and ``After``) from +the ``network-online.target``. + + +The defined type is used from ``role::base`` to create the resources +defined in the ``base::timers`` hiera hash. + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +description String +command String +on_calendar String +=============================== ======== ================================================ + + +``description`` +~~~~~~~~~~~~~~~ + +Human-oriented description of the service and timer. + +``command`` +~~~~~~~~~~~ + +Path to the command to invoke into the service. It should be an absolute path +and a check is performed against this. + +``on_calendar`` +~~~~~~~~~~~~~~~ +The definition of the timer execution time. See `OnCalendar` on systemd.timer(5). + diff --git a/admin-guide/puppet/profiles/epics.rst b/admin-guide/puppet/profiles/epics.rst new file mode 100644 index 00000000..0a2ff2d7 --- /dev/null +++ b/admin-guide/puppet/profiles/epics.rst @@ -0,0 +1,20 @@ +``profile::epics`` +================== + +Install and configure Epics. + + +Parameters +---------- + +============ ======== =========== +**Name** **Type** **Default** +------------ -------- ----------- +epics_func string - +============ ======== =========== + + +``epics_func`` +~~~~~~~~~~~~~~ + +A command written to ``/etc/epics_func.conf``, followed by ``>/dev/null``. diff --git a/admin-guide/puppet/profiles/filecopy.rst b/admin-guide/puppet/profiles/filecopy.rst new file mode 100644 index 00000000..4c56c0ee --- /dev/null +++ b/admin-guide/puppet/profiles/filecopy.rst @@ -0,0 +1,37 @@ +``profile::filecopy`` +===================== + +This module allows to copy file on the host using a git repository as +the source. + +The purpose of this module is to distribute files that are not +created/configured with other modules, usually files very specific +eg. scripts for very specific environments. + +With this module is possible to specifiy only single files, so no +directory or recursion is possible. + +The source files are taken from the master branch of a git repo that +should be accessible without authentication. Or anyway accessible from +the host where the files have to be copied (eg. via a proper ssh key). + +A section like the following in hiera will copy on file ``/tmp/test1`` +the content of +``https://git.psi.ch/talamo_i/copy-file-test/raw/master/abc``:: + + filecopy::files: + '/tmp/test1': + repo: 'talamo_i/copy-file-test' + path: 'abc' + mode: '0600' + owner: 'talamo_i' + +You can additionally specify the group owner of the file: + group: 'apache' + + +This module is included by default and ``filecopy::files`` is empty by +default. + +To copy files just define properly the ``filecopy::files`` variable. + diff --git a/admin-guide/puppet/profiles/files.rst b/admin-guide/puppet/profiles/files.rst new file mode 100644 index 00000000..5ac59359 --- /dev/null +++ b/admin-guide/puppet/profiles/files.rst @@ -0,0 +1,27 @@ +``profile::files`` +================== + +This profile creates symlinks. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +symlinks hash hiera('files::symlinks') +=============================== ======== ================================================ + + +``symlinks`` +~~~~~~~~~~~~ + +A hash specifying symlinks to be created. The keys of the hash are the absolute +pathnames of the symlinks, the values of the hash are the corresponding symlink +targets. + +Example:: + + files::symlinks: + '/opt/foo': '/var/lib/foo' diff --git a/admin-guide/puppet/profiles/ganglia_client.rst b/admin-guide/puppet/profiles/ganglia_client.rst new file mode 100644 index 00000000..607e8370 --- /dev/null +++ b/admin-guide/puppet/profiles/ganglia_client.rst @@ -0,0 +1,36 @@ +``profile::ganglia_client`` +============================ + +This module installs and configures Ganglia's gmond. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +grid string hiera('ganglia::grid') +cluster string hiera('ganglia_client::cluster') +n/a hash hiera('ganglia::grid_${GRID}') +=============================== ======== ================================================ + + +``grid`` +~~~~~~~~ + +The name of the Ganglia grid the client is a part of. + + +``cluster`` +~~~~~~~~~~~ + +The name of the Ganglia cluster within the grid the client is a part of. + + +``grid_${GRID}`` +~~~~~~~~~~~~~~~~ + +The definition of the grid. See the :doc:`ganglia_server documentation +<../profiles/ganglia_server>` for details. + diff --git a/admin-guide/puppet/profiles/ganglia_server.rst b/admin-guide/puppet/profiles/ganglia_server.rst new file mode 100644 index 00000000..62a525fd --- /dev/null +++ b/admin-guide/puppet/profiles/ganglia_server.rst @@ -0,0 +1,104 @@ +``profile::ganglia_server`` +=========================== + +This module configures the following Ganglia server components: + +- the web interface (using Apache) +- one gmond for each cluster to be monitored by this server + +The latter is a little unusual. Normally, the gmonds collecting the data for +each cluster, which are then queried by gmetad, are part of the cluster. The +implementation chosen by this module makes it easier to deal with firewalls. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +grid string hiera('ganglia::grid') +grid_${GRID} hash hiera('ganglia::grid_${GRID}') +=============================== ======== ================================================ + + +``grid`` +~~~~~~~~ + +This string identifies the grid (ie the collection of clusters) this server +monitors. The definition of the grid is taken from the Hiera value +``grid_${GRID}``. + + +``grid_${GRID}`` +~~~~~~~~~~~~~~~~ + +The definition of the Ganglia grid this server is responsible for. It is a hash +containing the following keys: + + +``name`` +,,,,,,,, + +The name of the grid as used in the web interface. + + +``ui`` +,,,,,, + +The FQDN of the server hosting the web UI and collecting the data for the grid. +A system with role ``ganglia_server`` will compare its own FQDN to this value +and fail if they are not equal. Clients will need this value to know where they +they should send their metrics. + + +``clusters`` +,,,,,,,,,,,, + +A hash of cluster definitions. The keys are the IDs of the clusters, ie. what a +client expects to find in ``ganglia::cluster``. The values are hashes containing +the following attributes: + +``name`` +........ + +The user-friendly name of the cluster to be used in the web UI. + +``port`` +........ + +The port used within the cluster. The first cluster should use 8649 (the Ganglia +standard port), the next cluster should use 8650, and so on. + + +Examples +-------- + +Suppose we have a Ganglia grid for Swissfel (sysdb_env == swissfel). +The we could put the following in Hiera. + +In ``swissfel.yaml`` we would define grid, say ``sfel``, and set the grid for +all systems in the ``swissfel`` environment to ``sfel``:: + + + ganglia::grid: 'sfel' + + ganglia::grid_sfel: + name: 'SwissFEL' + ui: 'gmeta00.psi.ch' + clusters: + 'sf-daqbuf': + name: 'DAQ Buffers' + port: 8649 + 'sf-athos' + name: 'Athos Beamline Systems' + port: 8650 + +In the ``swissfel/daqbuf.yaml`` we would then set the cluster to ``sf-daqbuf``:: + + ganglia::cluster: 'sf-daqbuf' + +In ``swissfel/athos.yaml`` on the other hand, we would set the cluster to +``sf-athos``:: + + ganglia::cluster: 'sf-athos' diff --git a/admin-guide/puppet/profiles/gnome.rst b/admin-guide/puppet/profiles/gnome.rst new file mode 100644 index 00000000..5caf5689 --- /dev/null +++ b/admin-guide/puppet/profiles/gnome.rst @@ -0,0 +1,46 @@ +``profile::gnome`` +================== + +This module installs and configures the Gnome desktop environment. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +banner_message string +enable_update_notifications bool +favorites list +keyboard_layouts list +=============================== ======== ================================================ + + +``banner_message`` +~~~~~~~~~~~~~~~~~~ + +The message displayed above the login prompt. + + +``enable_update_notifications`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Whether or not ``gnome-software`` is started at the beginning of a session to +notify the user about available updates. + + +``favorites`` +~~~~~~~~~~~~~ + +The applications/directories/etc to be displayed in the *Favorites* menu and/or +the Gnome dock. Each member of the list must be a string containing the full +name (not path!) of the ``.desktop`` file, eg. ``gnome-terminal.desktop`` for +the Gnome Terminal. + + +``keyboard_layouts`` +~~~~~~~~~~~~~~~~~~~~ + +A list of the keyboard mappings which should be available on the login screen. +The first mapping in the list is the default. diff --git a/admin-guide/puppet/profiles/gpfs.rst b/admin-guide/puppet/profiles/gpfs.rst new file mode 100644 index 00000000..aff0ed67 --- /dev/null +++ b/admin-guide/puppet/profiles/gpfs.rst @@ -0,0 +1,91 @@ +``profile::gpfs`` +================= + +Install and configure the `GPFS parallel file system +`_. + +The installation also includes the configuration of the rpm repositories. + +Parameters +---------- + +================= ========== =========== +**Name** **Type** **Default** +----------------- ---------- ----------- +version string +repo_base_url string +setup_repos bool true +setup_pmsensors bool true +setup_pmcollector bool false +setup_ces bool false +setup_gui bool false +fs_opts hash empty hash +================= ========== =========== + + +``version`` +~~~~~~~~~~~ + +The version of GPFS to install. + + +``repo_base_url`` +~~~~~~~~~~~~~~~~~ + +The base URL of the GPFS repositories. Each version of GPFS comes in its own +repositories, which are assumed to be located under +``${repo_base_url}/${version}/``. + +Repository configuration is subject to `setup_repos`_. + + +``setup_repos`` +~~~~~~~~~~~~~~~ + +Whether or not to configure the GPFS repositories. + + +``setup_pmsensors`` +~~~~~~~~~~~~~~~~~~~ + +Install packages needed to run the pmsensors service. + +``setup_pmcollector`` +~~~~~~~~~~~~~~~~~~~~~ + +Install packages needed to run the pmcollector service. + +``setup_ces`` +~~~~~~~~~~~~~ + + +``setup_gui`` +~~~~~~~~~~~~~ + +Install packages needed to run the gpfsgui service. + +``fs_opts`` +~~~~~~~~~~~ + +By default a GPFS filesystem will be mounted on all nodes of +the cluster with the same option, eg. it will be read-write if +the filesystem as been defined with read-write access (see ``mmfs`` +for the mount options). + +It is possible to override these option on a host specific base +configuring a file named ``/var/mmfs/etc/localMountOptions.`` +with one option per line. + +Please note that even if the parameter is ``fs_opts`` in the code, +the hiera variable is called ``fs_mount_opts``. + +The following hiera code can be used to make the ``beamline`` filesystem +mounted in read-only mode:: + + gpfs::fs_mount_opts: + 'beamline': ['ro'] + + + + + diff --git a/admin-guide/puppet/profiles/grafana.rst b/admin-guide/puppet/profiles/grafana.rst new file mode 100644 index 00000000..a80e6e93 --- /dev/null +++ b/admin-guide/puppet/profiles/grafana.rst @@ -0,0 +1,65 @@ +``profile::grafana`` +============================ + +This module installs and configures Grafana server. +It requires a SSL cert/key since the server will be provided over HTTPS. + +The system uses AD authentication for users and allows anonymous user +with view-only capabilities. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +vhost string hiera('grafana::vhost', FQDN) +servers array hiera('grafana::influxdb_servers') +admin_groups array hiera('grafana::admin_groups') +editor_groups array hiera('grafana::editor_groups') +admin_pw string hiera('grafana::admin_pw') +cert string hiera('grafana::tls_cert') +key string hiera('grafana::tls_key') +=============================== ======== ================================================ + + +``vhost`` +~~~~~~~~ + +The hostname through which the server will provide http/https service. +By default it corresponds to the FQDN, but in case of aliases or Round-Robin DNS it can be different. + +``servers`` +~~~~~~~~~~~ + +A list of influx db servers url to query for data. +Each server should be specified with a URL like ``http://hostname:8086``. + +The list of services will be queried to get the list of available databases and +the corresponding data sources will be automatically created. +The generation of the data sources happens when the list of server files or automatically every day. + +``admin_groups`` +~~~~~~~~~~~~~~~~ + +The list of unix groups that will have full (admin) rights when logging into the server. +See `this `_ for further details.ls. + +``editor_groups`` +~~~~~~~~~~~~~~~~ + +The list of unix groups that will have editor rights when logging into the server. +See `this `_ for further details. + +``admin_pw`` + +Password of the ``admin`` user. + +``cert`` + +SSL public certificate of the HTTPS server. + +``key`` + +Private key matching with the SSL certificate. diff --git a/admin-guide/puppet/profiles/icewm.rst b/admin-guide/puppet/profiles/icewm.rst new file mode 100644 index 00000000..bf70ce6a --- /dev/null +++ b/admin-guide/puppet/profiles/icewm.rst @@ -0,0 +1,15 @@ +``profile::icewm`` +================== + +This profile installs and configures the IceWM window manager. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +toobar_apps hash hiera('icewm::toolbar::apps', {}) +menu_apps hash hiera('icewm::menu::apps', {}) +=============================== ======== ================================================ diff --git a/admin-guide/puppet/profiles/icinga/checks/gpfs.rst b/admin-guide/puppet/profiles/icinga/checks/gpfs.rst new file mode 100644 index 00000000..9c9a0d50 --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/checks/gpfs.rst @@ -0,0 +1,41 @@ +``profile::icinga::checks::gpfs`` +======================================== + +This profile is called when ``gpfs`` is being configured. + +Setup specific checks for GPFS: + * It will check that **GPFS** service is running correctly. + * Also checks node status with ``mmhealth``. + +Parameters +---------- + +=================== ========== ============================================================= +**Name** **Type** **Default** +------------------- ---------- ------------------------------------------------------------- +check_unhealth_only Boolean ``icinga::checks::options::gpfs::ignoretips:`` **``true``** +check_ignore_tips Boolean ``icinga::checks::options::gpfs::unhealth:`` **``false``** +=================== ========== ============================================================= + +``check_unhealth_only`` +~~~~~~~~~~~~~~~~~~~~~~ + +By default ``mmhealth`` is called with the option ``--unhealth``. This shows only **unhealthy** problems. This can be disabled +by setting ``icinga::checks::options::gpfs::unhealth: false``, in this case ``mmhealth`` will also report about **healthy** checks. + + +``check_ignore_tips`` +~~~~~~~~~~~~~~~~~~~~~ + +**TIPS** errors are considered ``[WARNING]`` by default. As these are configuration tips, some admins can consider that tips are ``[OK]`` +in their clusters. This behaviour can be changed by setting ``icinga::checks::options::gpfs::ignoretips: true``, which will consider **TIPS** as ``[OK]``. + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/checks/hp/smart_array.rst b/admin-guide/puppet/profiles/icinga/checks/hp/smart_array.rst new file mode 100644 index 00000000..2ebff095 --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/checks/hp/smart_array.rst @@ -0,0 +1,29 @@ +``profile::icinga::checks::hp::smart_array`` +======================================== + +This profile is automatically called when a HP Smart Array is detected through facter from the +``profile::platform::hewlett_packard`` class. + +Setup checks for HP Smart Arrray. + * Will setup a check executing ``ssacli`` in order to check the following components: + * **Controller(s)** status, **Cache** status (when configured) & **Battery** status (when present) + * **Logical Drive(s)** status + * **Physical Drive(s)** status + +Parameters +---------- + +================= ========== ========================================================= +**Name** **Type** **Default** +----------------- ---------- --------------------------------------------------------- +================= ========== ========================================================= + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/checks/nvidia.rst b/admin-guide/puppet/profiles/icinga/checks/nvidia.rst new file mode 100644 index 00000000..24566abb --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/checks/nvidia.rst @@ -0,0 +1,31 @@ +``profile::icinga::checks::nvidia`` +======================================== + +This profile is called when ``nvidia`` is being configured through ``cuda`` + +Setup specific checks for the Puppet Client: + * It will check that ``nvidia-smi`` correctly responds with the NVIDIA GPU cards. + When kernel is updated, it may cause to boot up with the NVIDIA drivers. + +It will return OK and the list of GPUS when ``nvidia-smi`` correctly answers. +It will return CRITICAL and the error message when ``nvidia-smi`` is unable to detect GPU cards. + +Most probably in the future drivers will be directly checked. + +Parameters +---------- + +================== ========== ============================================================= +**Name** **Type** **Default** +------------------ ---------- ------------------------------------------------------------- +================== ========== ============================================================= + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/checks/puppet_client.rst b/admin-guide/puppet/profiles/icinga/checks/puppet_client.rst new file mode 100644 index 00000000..104b8ef4 --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/checks/puppet_client.rst @@ -0,0 +1,33 @@ +``profile::icinga::checks::puppet_client`` +======================================== + +This profile is called when ``puppet`` client is being configured. + +Setup specific checks for the Puppet Client: + * It will check that the current running environment is ``puppet_environment``. + Otherwise it will return a **nagios** ``WARNING`` message and error. + +Parameters +---------- + +================== ========== ============================================================= +**Name** **Type** **Default** +------------------ ---------- ------------------------------------------------------------- +puppet_environment String hiera('icinga::checks::options::puppet_environment',**prod**) +================== ========== ============================================================= + +``puppet_environment`` +~~~~~~~~~~~~~~~~~~~~~~ + +This setting defaults to the puppet environment ``prod``. Can be changed from YAML by setting +``icinga::checks::options::puppet_environment`` to a different value. + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/checks/service.rst b/admin-guide/puppet/profiles/icinga/checks/service.rst new file mode 100644 index 00000000..2149cf09 --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/checks/service.rst @@ -0,0 +1,35 @@ +``profile::icinga::checks::service`` +========================================== + +This class will configure Nagios checks for one or more ``systemctl`` services. This can be done by setting +a list of services with the ``icinga::checks::service::list`` *hiera* setting. ``check_service`` is the +script that will be in charge for that, which is also used by other Nagios scripts (i.e. ``check_slurm`` & +``check_gpfs``) to check specific services for these alarms. + +Parameters +---------- + +===================== ========== ========================================================================= +**Name** **Type** **Default** +--------------------- ---------- ------------------------------------------------------------------------- +service_list Array ``'icinga::checks::service::list'``, defaults to ``'[]'`` +===================== ========== ========================================================================= + +``service_list`` +~~~~~~~~~~~~~~~~~~~~~~ + +The default value is an empty ``Array`` (``'[]'``). Hence, no ``systemctl`` services are checked. +This value can be overwritten with a list of services. In example:: + icinga::checks::service::list: + - ntpd + - postfix + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/checks/slurm.rst b/admin-guide/puppet/profiles/icinga/checks/slurm.rst new file mode 100644 index 00000000..b2614129 --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/checks/slurm.rst @@ -0,0 +1,87 @@ +``profile::icinga::checks::slurm`` +========================================== + +This profile should be called when **Slurm** (server, cn, ui) is being configured. + +Setup specific checks for Slurm nodes: + * It can check ``slurmd`` service. This check makes sense on computing nodes running ``slurmd``. + * It can check ``munge`` service. This check makes sense on any node with a configured **Slurm** client/server. + * It can check ``slurmctld`` service. This check makes sense on server nodes, will disable ``slurmd`` check. + * It can check ``slurmdbd`` service. This check makes sense on server nodes. + * It can check ``sinfo`` status, detecting miss-behaving nodes. + +By default, since the most common node in a **Slurm** cluster is a computing node, this check will report about +``slurmd`` and ``munge`` status. + +Parameters +---------- + +===================== ========== ========================================================================= +**Name** **Type** **Default** +--------------------- ---------- ------------------------------------------------------------------------- +skip_munge Boolean ``icinga::checks::options::slurm::skip_munge`` **``false``** +skip_slurmd Boolean ``icinga::checks::options::slurm::skip_slurmd``: **``false``** +check_slurmdbd Boolean ``icinga::checks::options::slurm::check_slurmdbd`` **``false``** +check_slurmctld Boolean ``icinga::checks::options::slurm::check_slurmctld`` **``false``** +ignore_draining Boolean ``icinga::checks::options::slurm::ignore_draining`` **``false``** +ignore_drained Boolean ``icinga::checks::options::slurm::ignore_drained`` **``false``** +check_nodes Boolean ``icinga::checks::options::slurm::check_nodes`` **``false``** +no_reason Boolean ``icinga::checks::options::slurm::no_reason`` **``true``** +no_timestamp Boolean ``icinga::checks::options::slurm::no_timestamp`` **``false``** +===================== ========== ========================================================================= + +``skip_munge`` +~~~~~~~~~~~~~~~~~~~~~~ + +By default ``munge`` service is checked. Can be disabled by setting ``icinga::checks::options::slurm::skip_munge: false``. + +``skip_slurmd`` +~~~~~~~~~~~~~~~~~~~~~ + +By default ``slurmd`` service is checked. Can be disabled by setting ``icinga::checks::options::slurm::skip_slurmd: false``. + + +``check_slurmdbd`` +~~~~~~~~~~~~~~~~~~~~~~~ + +By default ``slurmdbd`` service is disabled. Can be enabled by setting ``icinga::checks::options::slurm::check_slurmdbd: true``. + +``check_slurmctld`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +By default ``slurmctld`` service is disabled. Can be enabled by setting ``icinga::checks::options::slurm::check_slurmctld: true``, in this case ``icinga::checks::options::slurm::skip_slurmd`` +should be also set to ``true``. + +`ignore_draining`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +By default nodes in ``draining`` state are checked and will be reported as ``[WARNING]``. This can be disabled by setting ``icinga::checks::options::slurm::ignore_draining: true``. +When set to ``true``, ``draining`` nodes will be reported anyway but will be considered as ``[OK]`` + +``ignore_drained`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +By default nodes in ``drained`` state are checked and will be reported as ``[WARNING]``. This can be disabled by setting ``icinga::checks::options::slurm::ignore_drained: true``. +When set to ``true``, ``drained`` nodes will be reported anyway but will be considered as ``[OK]`` + +``no_reason`` +~~~~~~~~~~~~~~~~~~~~~ + +By default **no** ``Reason`` is reported. This is because it will add extra text to the alarm output when nodes are ``drained``/``draining``/``down``/``failed``. +Printing ``Reason`` can be turned on by setting ``icinga::checks::options::slurm::no_reason: false``. + +``no_timestamp`` +~~~~~~~~~~~~~~~~~~~~~ + +By default ``Timestamp`` is being reported. Timestamp shows the date and time when a node was set ``drained``/``draining``/``down``/``failed``. +As this setting adds extra text in the alarm, it can be disabled by setting ``icinga::checks::options::slurm::no_reason: true``. + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/client.rst b/admin-guide/puppet/profiles/icinga/client.rst new file mode 100644 index 00000000..f650de3e --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/client.rst @@ -0,0 +1,56 @@ +``profile::icinga::client`` +========================== + +This profile installs and configured the ``nrpe`` service: + * Installs ``mod_gearman-static``, ``nrpe-selinux``, ``nrpe`` + * Instals Nagios plugins: ``nagios-plugins-disk``, ``nagios-plugins-load`` + * Manages the NRPE service and ensures that is ``running`` and ``enabled`` + * Allows to configure the ``nrpe.cfg`` file with the ``icinga::client::servers`` setting which defaults to ``[ 'emonma00.psi.ch','wmonag00.psi.ch','emonag00.psi.ch' ]`` (default value on fresh *nrpe* installations) + * SELinux policy setup to allow ``nagios_run_sudo``. + +Is strictly important to set up ``aaa::allow_sudoers_d`` to ``true``:: + ``aaa::allow_sudoers_d: true`` + +By setting ``allow_sudoers_d`` to ``true``, we enable by default the +use of the directory ``/etc/sudoers.d/``. This will required for some Nagios +alarms. + +Parameters +---------- + +================= ========== ========================================================= +**Name** **Type** **Default** +----------------- ---------- --------------------------------------------------------- +servers Array hiera('icinga::client::servers') +blame Array hiera('icinga::client::dont_blame_nrpe', 0) +================= ========== ========================================================= + +``servers`` +~~~~~~~~~~~~~~~~~ + +The local parameter for ``icinga::client::servers`` is ``servers``. Defaults to ``[ 'emonma00.psi.ch','wmonag00.psi.ch','emonag00.psi.ch' ]`` +which is the default value in the ``nrpe.cfg`` file on fresh ``nrpe`` installations. Somebody can +overwrite this value with a new ``Array`` of Icinga servers. This ``Array`` will be converted to ``String`` +afterwards:: + + ... + Array $servers = hiera('icinga::client::servers'), + ... + $icinga_servers = join($servers,",") + ... + +``blame`` +~~~~~~~~~ + +With this option, the NRPE will allow clients to specify arguments in the commands. By default this is ``disabled``: arguments must be +specified in the NRPE daemon side and not from the client side. This option modifies the setting ``dont_blame_nrpe`` in the ``nrpe.cfg`` file. + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/icinga/nrpe.rst b/admin-guide/puppet/profiles/icinga/nrpe.rst new file mode 100644 index 00000000..eb96450f --- /dev/null +++ b/admin-guide/puppet/profiles/icinga/nrpe.rst @@ -0,0 +1,55 @@ +``profile::icinga::nrpe`` +========================== + +This profile is a function that configures ``nrpe`` and ``sudoers`` (whenever needed) for a specific command: + * Will create a ``/etc/nrpe.d/.cfg`` file for ``nrpe`` + * Will create a ``/etc/sudoers.d/`` file for ``sudoers`` (if ``sudo`` is required) + +Parameters +---------- + +================= ========== ========================================================= +**Name** **Type** **Default** +----------------- ---------- --------------------------------------------------------- +command String +sudo Boolean ``false`` +notifications_enabled Boolean ``true`` +================= ========== ========================================================= + +``command`` +~~~~~~~~~~~~~~~~~ + +Full path for the command to be configured in the ``nrpe.d`` file. This will be translated +in the ``nrpe.d`` as:: + + # sudo = true + command[${title}]=/usr/bin/sudo ${command} + + # sudo = false + command[${title}]=${command} + +``sudo`` +~~~~~~~~~ + +Whether ``sudo`` is required or not for that command. By default is ``false``. +When set to ``true``, ``/usr/bin/sudo`` will be added to the ``nrpe`` command, and proper +``sudoers`` file will be configured. Example:: + + Defaults:nrpe !requiretty + nrpe ALL=(root) NOPASSWD: ${command} + +``notifications_enables`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Currently this settings has no effect. Will be used when exporting Nagios resources to the PuppetDB. +Please ignore it in the meantime. + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/infiniband.rst b/admin-guide/puppet/profiles/infiniband.rst new file mode 100644 index 00000000..3e3683c8 --- /dev/null +++ b/admin-guide/puppet/profiles/infiniband.rst @@ -0,0 +1,53 @@ +``profile::infiniband`` +======================= + +Installs and configures the Infiniband software stack. + + * New service ``ib-online`` is being installed, which will wait until IB gets online. The script ``/opt/pli/libexec/ib-check-active-ports`` is used for that. + * Setup of the ``/etc/sysconfig/network-scripts/ifcfg-${ib_ifname}`` files. + * Installation of ``/usr/local/bin/mlxup`` which is useful for checking firmware version and upgrade Mellanox IB cards directly from Mellanox. + * OFED repository + installation of the following packages: ``ibutils``, ``infiniband-diags``, ``mlnx-ofed-basic``, ``librdmacm-devel``, ``perftest``, ``infinipath-psm`` + +Parameters +---------- + +========== ========= ========================== +**Name** **Type** **Default** +---------- --------- -------------------------- +ib_ifname string *undef* +ib_ip string *undef* +ib_subnet string *undef* +repo_tag String *yum_client::repo_tag* +ofed_vers String *infiniband::ofed_version* +========== ========= ========================== + + +``ib_ifname`` +~~~~~~~~~~~~~ + +The name of the Infiniband interface. + + +``ib_ip`` +~~~~~~~~~ + +The IP to be configured on the Infiniband interface. + + +``ib_subnet`` +~~~~~~~~~~~~~ + +The subnet to be used on the Infiniband interface in CIDR notation. + + +``repo_tag`` +~~~~~~~~~~~~ + +Which ``yum`` ``repo_tag`` should be used. In example, ``latest`` can be used. + + +``ofed_vers`` +~~~~~~~~~~~~~ + +OFED version to be installed and configured. Format: ``X.Y-A.B.C.D``, where X.Y is the major OFED version and +A.B.C.D is the subversion. diff --git a/admin-guide/puppet/profiles/jupyterhub.rst b/admin-guide/puppet/profiles/jupyterhub.rst new file mode 100644 index 00000000..e86fd822 --- /dev/null +++ b/admin-guide/puppet/profiles/jupyterhub.rst @@ -0,0 +1,138 @@ +``profile::jupyterhub`` +===================== + +This module configures the node for running a jupyterhub service +able to spawn singleuser servers on cluster nodes via SLURM + +The jupyterhub software itself will not be installed by this +module. It is expected to be found in an existing environment +usually installed separately by ``conda`` and centrally served on a +distributed file system (There is a reference installation in the +environment module ``anaconda/2019.03`` within the +``jupyterhub_dev_py36`` conda environment) + +Supported jupyterhub versions: jupyterhub-0.96 or the current +(as of 2019-05) development version 1.0.0b1. The development version is preferred +due to recent fixes that enable a clean shutdown on a batch cluster. + +Optional customization of User selectable options +------------------------------------------------- + +This installation uses the `optionsSpawner `_ plugin to offer user selectable +customizations on the spawning web page. By default, a simple dialog +with selectable partitions and runtime is offered. If a more extended +customization page is required, the administrator can create the file +``/etc/jupyterhub/optionsspawner_config.py`` and put additional options inside. +The jupyterhub main configuration file ``/etc/jupyterhub/jupyterhub_config.py`` +will check whether the file exists and load it. In this way we can +keep the puppet module more generic. + +Some adaptions may require deeper changes to the configuration file +and adaption of the puppet code + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +admin_users Array hiera('jupyterhub\:\:admin_users') +api_port Integer hiera('jupyterhub\:\:api_port', 8080) +env_setup String hiera('jupyterhub\:\:env_setup') +group_whitelist Array hiera('jupyterhub\:\:group_whitelist') +hub_port Integer hiera('jupyterhub\:\:hub_port', 8000) +hub_version String hiera('jupyterhub\:\:hub_version') +partitions Hash hiera('jupyterhub\:\:partitions') +tls_cert String hiera('jupyterhub\:\:tls_cert') +tls_key String hiera('jupyterhub\:\:tls_key') +=============================== ======== ================================================ + + + +``admin_users`` +~~~~~~~~~~~~~~~ + +A list of user names. These users will get access to the jupyterhub administration +web pages. + +Example: + +:: + + jupyterhub::admin_users: + - 'feichtinger' + - 'caubet_m' + - 'bliven_s' + - 'loktionova_n' + +``api_port`` +~~~~~~~~~~~~ + +Port number of the port on which the jupyterhub API will be listening (internally +used by jupyterhub for control communications) + +``env_setup`` +~~~~~~~~~~~~~ + +Lines to be inserted into the bash scripts for defining the +jupyterhub environment for both the server and the spawned client +sessions (it is important that the server and the singleserver +client host both run the same jupyterhub and spawner codes) + +Example: + +.. code:: bash + + export PMODULES_VERSION=1.0.0rc4 + source /opt/psi/config/profile.bash + module use unstable &> /dev/null + module load anaconda/2019.03 &> /dev/null + conda activate jupyterhub_dev + +``group_whitelist`` +~~~~~~~~~~~~~~~~~~~ + +A list of unix groups that will be granted access to this jupyterhub. + +Example: + +:: + + jupyterhub::group_whitelist: + - 'svc-cluster_merlin5' + +``hub_port`` +~~~~~~~~~~~~ + +The main port to which clients will connect. + +``hub_version`` +~~~~~~~~~~~~~~~ + +Version String of jupyterhub. Currently either '0.96' or '1.0.0b2' is +supported. Recommended: '1.0.0b2'. + +partitions +~~~~~~~~~~ + +SLURM partitions to be offered in the default option selection. Should be +a mapping of partition names to descriptive strings. + +Example: + +:: + + jupyterhub::partitions: + 'test' : 'Test nodes' + 'merlin' : 'merlin standard' + 'gpu' : 'GPU nodes' + +tls_cert +~~~~~~~~~ + +String (PEM Format) of the web server certificate + +tls_key +~~~~~~~~ + +Eyaml encoded string of the web server certificate key (PEM format) diff --git a/admin-guide/puppet/profiles/kdump_client.rst b/admin-guide/puppet/profiles/kdump_client.rst new file mode 100644 index 00000000..4299bff2 --- /dev/null +++ b/admin-guide/puppet/profiles/kdump_client.rst @@ -0,0 +1,42 @@ +``profile::kdump_client`` +========================= + +This profile manages the ``kdump`` service. It automatically reserves memory for +the crash kernel. + + +Parameters +---------- + +=========== ======== ================================================ +**Name** **Type** **Default** +----------- -------- ------------------------------------------------ +crashkernel string hiera('kdump_client::crashkernel') +target string hiera('kdump_client::target') +=========== ======== ================================================ + + +``crashkernel`` +~~~~~~~~~~~~~~~ + +Configures the kernel parameter ``crashkernel``, which specifies the amount of +memory to be reserved for the crash kernel. This can be ``auto`` or ``xxxM``. +Further information is provided by `Red Hat +`_. + + +``target`` +~~~~~~~~~~ + +The target for kernel dumps as documented in ``kdump.conf(5)``. Currently SSH +targets do not work, as there is no way to specify an SSH key. + + +Examples +-------- + +Transfer kernel dumps to a remote server using NFS:: + + class {'kdump': + target => 'nfs some-server.psi.ch/crashes/', + } diff --git a/admin-guide/puppet/profiles/local_accounts.rst b/admin-guide/puppet/profiles/local_accounts.rst new file mode 100644 index 00000000..cefb491f --- /dev/null +++ b/admin-guide/puppet/profiles/local_accounts.rst @@ -0,0 +1,99 @@ +``profile::local_accounts`` +=========================== + +This module helps managing local users and groups. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +group_defs hash hiera('local_accounts::group_defs') +groups hash hiera('local_accounts::groups') +user_defs hash hiera('local_accounts::user_defs') +users list hiera('local_accounts:users') +=============================== ======== ================================================ + + +``group_defs`` +~~~~~~~~~~~~~~ + +A hash containing the definitions of local groups. The keys are the group names, +the values are the numeric group IDs. + + +Example:: + + local_accounts::group_defs: + 'my_local_group': 673 + +Also see `groups`_. + + +``groups`` +~~~~~~~~~~ + +A list containing the names of the local groups to be created. The definition +for each group is taken from `group_defs`_. + + +``user_defs`` +~~~~~~~~~~~~~ + +A hash containing the definitions of local users. The keys are the user names, +the values are hashes containing the usual user properties, ie: + +============ ========================== +``password`` password hash (optional) +``uid`` numeric UID (required) +``gid`` numeric GID (required) +``comment`` comment (optional) +``home`` home directory (required) +``shell`` shell (required) +============ ========================== + + +``users`` +~~~~~~~~~ + +A list of the users to be created. The definition of each user is taken from +`user_defs`_. + + +Examples +-------- + +The following defines three users and one group, but only creates one each:: + + local_accounts::group_defs: + 'archadm': 503 + + local_accounts::user_defs: + 'ioc': + 'uid': 500 + 'gid': 9102 + 'home': '/home/ioc' + 'shell': '/bin/bash' + 'comment': 'IOC Account' + + 'slsop': + 'uid': 501 + 'gid': 9102 + 'home': '/home/slsop' + 'shell': '/bin/bash' + 'comment': 'SLS Operator' + + 'archadm': + 'uid': 503 + 'gid': 503 + 'home': '/home/archadm' + 'shell': '/bin/bash' + 'comment': '' + + local_accounts::groups: + - 'archadm' + + local_accounts::users:: + - 'archadm' diff --git a/admin-guide/puppet/profiles/log_client.rst b/admin-guide/puppet/profiles/log_client.rst new file mode 100644 index 00000000..39b089ba --- /dev/null +++ b/admin-guide/puppet/profiles/log_client.rst @@ -0,0 +1,91 @@ +``profile::log_client`` +======================= + +This module manages the local logging-related configuration. + +It can make the journal permanent, enable or disable legacy configuration files +(e.g. ``/var/log/messages``), and configure log forwarding. + + +Parameters +---------- + +============================ ======== ================================================== +**Name** **Type** **Default** +---------------------------- -------- -------------------------------------------------- +forward_to list hiera('log_client::forward_to', []) +legacy_logs bool hiera('log_client::legacy_logs') +persistent_journal bool hiera('log_client::persistent_journal') +journal_system_keep_free string hiera('log_client::journal_system_keep_free') +journal_system_max_file_size string hiera('log_client::journal_system_max_file_size') +journal_system_max_use string hiera('log_client::journal_system_max_use') +============================ ======== ================================================== + + +``journal_system_keep_free`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +How much space :manpage:`systemd-journald(8)` should keep free for non-journal +use in ``/var/log``. In addition to the syntax described in +:manpage:`journald.conf(5)` we also support percentages, ie ``'25%'`` means that +the journal will leave at least 25% of ``/var/log`` for other uses. + + +``journal_system_max_file_size`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The maximum size of individual journal files. + + +``journal_system_max_use`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The maximum amount of space that the journal is allowed to use. In addition to +the syntax described in :manpage:`journald.conf(5)` we also support percentages, +ie ``'50%'`` means that the journal can use at most 50% of ``/var/log``. + + +``forward_to`` +~~~~~~~~~~~~~~ + +An array of FQDNs, possibly prefixed with ``@`` for enabling TCP and followed by +a port number. Log messages are forwarded to all entries in this list. + + +``legacy_logs`` +~~~~~~~~~~~~~~~ + +A boolean controlling whether the legacy log files (``/var/log/messages`` etc) +should be created (true) or not (false). + + +``persistent_journal`` +~~~~~~~~~~~~~~~~~~~~~~ + +A boolean controlling whether the journal should be persistent (true) or not +(false). + + +Examples +-------- + +This profile is included in the base role. To customize the log_client in a +role, do this:: + + class role::some_role () { + class {'role::base': + include_log_client => false, + ... + } + + class {'profile::log_client': + legacy_logs => false, + persistent_journal => true, + } + +In Hiera, configure forwarding to ``log1`` using UDP on port 1514 and to +``log2`` using TCP (on port 514):: + + log_client::forward_to: + - 'log1.psi.ch:1514' + - '@log2.psi.ch' diff --git a/admin-guide/puppet/profiles/log_server.rst b/admin-guide/puppet/profiles/log_server.rst new file mode 100644 index 00000000..2c87648a --- /dev/null +++ b/admin-guide/puppet/profiles/log_server.rst @@ -0,0 +1,25 @@ +``profile::log_server`` +============================= + + +Parameters +---------- + +======== ========= ================================= +**Name** **Type** **Default** +-------- --------- --------------------------------- +base_dir string hiera('log_server::base_log_dir') +rules list hiera('log_server::rules') +======== ========= ================================= + + +``base_dir`` +~~~~~~~~~~~~ + +This parameter designates the directory where the log data is stored. + + +``rules`` +~~~~~~~~~ + +A list of rules to add to the end of ``/etc/rsyslog.conf``. diff --git a/admin-guide/puppet/profiles/mkresource/files.rst b/admin-guide/puppet/profiles/mkresource/files.rst new file mode 100644 index 00000000..685fc7cb --- /dev/null +++ b/admin-guide/puppet/profiles/mkresource/files.rst @@ -0,0 +1,107 @@ +``profile::mkresource::files`` +============================== + +``profile::mkresource::files`` is a puppet ``define`` (a.k.a. ``function``) which easily allows the creation of files +through the puppet ``file`` resource (through the ``create_resources`` puppet function. + +This ``define`` is intended to be called in a controlled way from a ``role`` or from another ``profile``, through an ``Array`` +list. However, it also allows the possibility to provide freedom by calling it through a ``Hash`` of files. Further information +is explained below": + +* ``Array``: In order to have more control on the files that are being created. In example:: + + # Begin: puppet class + class role::hpc::ui ( + Array $scratch = hiera('base::scratch', []), + ... + ) { + ... + profile::mkresource::files { "scratch": + files => $scratch, + defaults => { mode => '1777' }; + } + ... + } + # End: puppet class + + # Begin: hiera call + base::scratch: + - '/scratch' + - '/ssd-scratch' + # End: hiera call + +* ``Hash``: This will provide more flexibility from the user side. Only really strange cases will be allowed. Example:: + + # Begin: puppet class + class role::hpc::ui ( + Array $scratch = hiera('base::scratch', {}), + ... + ) { + ... + profile::mkresource::files { "scratch": + files => $scratch; + } + ... + } + # End: puppet class + + # Begin: hiera call + base::scratch: + '/scratch': + ensure: directory + mode: '1777' + owner: 'root' + group: 'root' + '/ssd-scratch' + ensure: directory + mode: '1770' + group: 'svc-cluster_merlin5' + # End: hiera call + +Parameters +---------- + +========== ==================== ========================== +**Name** **Type** **Default** +---------- -------------------- -------------------------- +$files Variant[Array, Hash] {} +$defaults Hash {} +========== ==================== ========================== + + +``files`` +~~~~~~~~~~~~~ +Defaults to ``Hash`` type ``{}``. Whenever is an ``Array``, it will be converted to ``Hash`` as ``create_resources`` is used and +it always expects a ``Hash``. + +Two different call examples: + +* ``Hash``:: + + base::scratch: + '/scratch': + ensure: directory + mode: '1777' + owner: 'root' + group: 'root' + '/ssd-scratch' + ensure: directory + mode: '1770' + group: 'svc-cluster_merlin5' + +* ``Array``:: + + base::scratch: + - '/scratch' + - '/ssd-scratch' + +``defaults`` +~~~~~~~~~ + +Defaults to empty ``Hash``. Should contain ``file`` resource parameters (in example, ``mode``, ``owner``, ``group``, ``ensure``, etc.) +Example:: + + profile::mkresource::files { "scratch": + files => [ '/scratch', '/ssd-scratch' ], + defaults => { mode => '1777' }; + } diff --git a/admin-guide/puppet/profiles/mounter.rst b/admin-guide/puppet/profiles/mounter.rst new file mode 100644 index 00000000..c99335eb --- /dev/null +++ b/admin-guide/puppet/profiles/mounter.rst @@ -0,0 +1,191 @@ +``profile::mounter`` +==================== + +This module manages mounts and installs filesystem-specific utilities. + +Mounts are configured using the Puppet ``mount`` resource type, ie. they get +added to ``/etc/fstab``. Auto-mounts are implemented by adding the +``x-systemd.automount`` option. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +mounts Array [] +def::$NAME Hash None +cifs_files Array [] +cifs::def::$NAME Hash None +=============================== ======== ================================================ + + +``mounter::def::$NAME`` +~~~~~~~~~~~~~~~~~~~~~~~ + +A hash defining a mount ``$NAME`` which can then be referenced by a module or +through the Hiera variable ``mounter::mounts``. + +The hash may contain the following keys: + +- ensure + + Is passed to the ``mount`` resource type unaltered with the following + exception. If the value is ``running``, it is changed to ``mounted``. This + ensures compatibility with an older version of this module. + +- mountpoint + + Will be created, if necessary. + +- device +- options +- type + + The filesystem type. Passed to the ``mount`` resource as ``fstype``. + +- auto + + Whether or not this mount should be automounted. Default: ``false``. + +- updatedb + + A boolean specifying whether :manpage:`updatedb(8)` should index the files + below the mountpoint. See the :doc:`updatedb <../components/updatedb>` + module for details. + + +``mounter::mounts`` +~~~~~~~~~~~~~~~~~~~ + +An array of strings referring to mount definitions to be configured on the +target system. Each string is the name of a mount defined through +`mounter::def::$NAME`_. + +``mounter::cifs::def::$NAME`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +A ``Hash`` containing information for creating an authentication file for CIFS +mounts. + +The ``Hash`` may contain the following keys: + +- ensure + + Is passwed to the ``profile::mounter::cifs`` resource, should contain any + possible value for the attribut ``ensure`` in a ``File`` resource type. + Usually, ``present`` will ensure that file is existing and updated will + ``absent`` will remove it. + +- path + + This is mandatory, should contain the path where the new credential file + should be located. Usually, ``/etc/cifs-utils`` would be a good option. + +- mode + + Defaults to ``0400``. It can be changed. + +- owner + + Defaults to ``root`` user. It can be changed. + +- group + + Defaults to ``group`` user. It can be changed. + +- cifs_username + + Must be defined. Should contain the ``username`` of the user allowed to + mount the CIFS mountpoint. + +- cifs_password + + Must be defined. Should contain the ``password`` of the user allowed to + mount the CIFS mountpoint, defined with ``cifs_username``. + + +``mounter::cifs`` +~~~~~~~~~~~~~~~~~ + +This defined type takes the paremters accepted for CIFS definitions (see +`mounter::cifs::de::$NAME`_). + + +Defined Types +------------- + +``mount`` +~~~~~~~~~ + +This defined type takes the parameters accepted for mount definitions (see +`mounter::def::$NAME`_). + + +Examples +-------- + +Local mount +~~~~~~~~~~~ + +A local mount can be configured in the following way:: + + mounter::def::scratch: + ensure: 'mounted' + mountpoint: '/scratch' + device: '/dev/vg_data/lv_scratch' + type: 'xfs' + + mounter::mounts: + - 'scratch' + + +To have the ``scratch`` mount from the previous example auto-mounted instead, +add the ``auto`` parameter:: + + mounter::def::scratch: + ensure: 'mounted' + mountpoint: '/scratch' + device: '/dev/vg_data/lv_scratch' + type: 'xfs' + auto: true + + mounter::mounts: + - 'scratch' + + +Supposedly this is a scratch mount, so we exclude the whole mount both from +backups and from updatedb. + +Remote Mount +~~~~~~~~~~~~ + +Remote CIFS mountpoint can be defined as follows:: + + mounter::cifs::def::cifs_mpc2375: + ensure: 'present' + path: '/etc/cifs-utils' + cifs_username: 'allowedWindowsUser' + cifs_password: 'ENC[PKCS7,MIIBeQYJKoZIhvc...]' + + mounter::cifs::files: + - 'cifs_mpc2375' + + mounter::def::emf: + ensure: 'running' + enable: 'true' + device: '//172.23.75.16/Users' + mountpoint: '/emf/jeol2200fs/k2' + type: 'cifs' + options: 'credentials=/etc/cifs-utils/cifs_mpc2375,uid=35667,gid=35270,forcegid,file_mode=0660,dir_mode=0770' + + mounter::mounts: + - 'emf' + +In the above example, we need to create a ``credentials`` file with `mounter::cifs::def::$NAME`_. This file will +be called ``cifs_mpc2375`` and will be located in ``/etc/cifs-utils`` and will contain information about the +username and password allowed to mount it. + +On the other hand, a mount ``emf`` is defined. You should specify in options the location of ``credentials``. +Other optional parameters are used. ``emf`` is mounted with type ``cifs``, which will automatically ensure that +proper ``cifs-utils`` package is installed. diff --git a/admin-guide/puppet/profiles/mta.rst b/admin-guide/puppet/profiles/mta.rst new file mode 100644 index 00000000..74a06520 --- /dev/null +++ b/admin-guide/puppet/profiles/mta.rst @@ -0,0 +1,16 @@ +``profile::mta`` +================ + +This module manages configures the system's MTA, currently +:manpage:`postfix(1)`. At the moment it only configures a relay host and +restricts access to the loopback interface. + + +Parameters +---------- + + +``relay`` +~~~~~~~~~ + +The FQDN of a host that all outgoing mail will be forwarded to for delivery. diff --git a/admin-guide/puppet/profiles/multipath.rst b/admin-guide/puppet/profiles/multipath.rst new file mode 100644 index 00000000..d71c6759 --- /dev/null +++ b/admin-guide/puppet/profiles/multipath.rst @@ -0,0 +1,147 @@ +``profile::multipath`` +======================= + +This profile configures :manpage:`multipath.conf`. + + +Parameters +---------- + +==================== ======== ============================================= +**Name** **Type** **Default** +-------------------- -------- --------------------------------------------- +wwid hash hiera_hash('multipath::wwid',{}) +blacklist_wwid hash hiera_hash('multipath::blacklist_wwid',{}) +devices array hiera_hash('multipath::devices',{}) +blacklist_devices array hiera_hash('multipath::blacklist_devices',{}) +blacklist_devnode array hiera_hash('multipath::blacklist_devnode',{}) +==================== ======== ============================================= + + +``wwid`` +~~~~~~~~ + +A hash containing the `allowed multipaths` by adding the `device alias` and its corresponding `'wwid'`. +In example: + +Hiera data:: + + profile::multipath::wwid: + 'vol1_a': '360080e50004315f40000087e5966df82' + 'vol1_b': '360080e5000431680000007c35966e03e' + 'vol1_c': '360080e50004315f4000008825966e1bf' + +will generate the following lines in the `'/etc/multipath.conf'` file:: + + multipaths { + multipath { + alias vol1_a + wwid "360080e50004315f40000087e5966df82" + } + multipath { + alias vol1_b + wwid "360080e5000431680000007c35966e03e" + } + multipath { + alias vol1_c + wwid "360080e50004315f4000008825966e1bf" + } + } + +``blacklist_wwid`` +~~~~~~~~~~~~~~~~~~ + +An hash containing `blacklisted multipaths` by adding the `device alias` and its corresponding `wwid`. In example: + +Hiera data:: + + profile::multipath::blacklist_wwid: + 'vol1_j': '360080e50004315f40000087e59aaaaaa' + +will generate the following lines in the `'/etc/multipath.conf'` file:: + + blacklist { + ... + multipath { + alias vol1_j + wwid "360080e50004315f40000087e59aaaaaa" + } + ... + } + + +``devices`` +~~~~~~~~~~~ + +An array containing `allowed devices` in the `multipath.conf` configuration. In example: + +Hiera data:: + + profile::multipath::devices: + - vendor: "Supermicro" + product: "Supermicro" + + +will generate the following lines in the `'/etc/multipath.conf'` file:: + + devices { + device { + vendor "Supermicro" + product "Supermicro" + } + } + + +``blacklist_devices`` +~~~~~~~~~~~~~~~~~~~~~ + +An array containing `blacklisted devices` in the `multipath.conf` configuration. In example: + +Hiera data:: + + profile::multipath::blacklist_devices: + - vendor: "HP" + product: "HP" + - vendor: "HP" + +will generate the following lines in the `'/etc/multipath.conf'` file:: + + blacklist { + ... + device { + vendor "HP" + product "HP" + } + device { + vendor "HP" + } + ... + } + + +``blacklist_devnode`` +~~~~~~~~~~~~~~~~~~~~~ + +An array containing a list of `node devices` that will be `blacklisted` in `multipath.conf`. +By default some `'devnodes'` are already included and fixed by default in the template file. These ones are the following:: + + devnode "^(ram|raw|loop|fd|md|dm-|sr|scd|st)[0-9]*" + devnode "^(td|hd|vd)[a-z]" + devnode "^(dcssblk)[0-9]*" + +In example, hiera data:: + + profile::multipath::blacklist_devnode: + - "sda" + - "sdb" + +will generate the following lines in the `'/etc/multipath.conf'` file:: + + blacklist { + ... + devnode "sda" + devnode "sdb" + ... + } + + diff --git a/admin-guide/puppet/profiles/networking.rst b/admin-guide/puppet/profiles/networking.rst new file mode 100644 index 00000000..8e0b37a8 --- /dev/null +++ b/admin-guide/puppet/profiles/networking.rst @@ -0,0 +1,65 @@ +``profile::networking`` +============================ + +This module configures most network-related settings, in particular: + +- DNS resolution (``/etc/resolv.conf``) +- DNS caching (via :manpage:`nscd(8)`) +- static host entries + +Notable exceptions are the firewall and ``/etc/hosts.{allow,deny}``. + +It also provides information about networks to other modules through the +variables listed below: + +- ``profile::networking::zone`` + + The name of network zone. This is used by the :doc:`ntp_client + <../profiles/ntp_client>` profile, for example, to determine which NTP servers + to use. + +- ``profile::networking::use_bastions`` + + This boolean indicates to the :doc:`aaa <../profiles/aaa>` profile whether SSH + access should be restricted to connections coming from the bastion hosts. + + +Notes: + +- the DNS cache is configured to be persistent, i.e. the cached data will + survive restarts of ``nscd.service``. To clear the cache, run ``nscd -i + hosts`` or ``systemctl reload nscd``. + + +Parameters +---------- + + +``dns_servers`` +~~~~~~~~~~~~~~~ + +The list of DNS servers (IP addresses) to be configured. This is only effective +if the client doesn't use DHCP (see `enable_dhcp`_). + + +``enable_dhcp`` +~~~~~~~~~~~~~~~ + +If this is true, then settings that are typically configured through DHCP (e.g. +DNS servers) are not touched by this module. + + +``enable_dns_caching`` +~~~~~~~~~~~~~~~~~~~~~~ + +This boolean determines whether DNS caching with nscd is enabled (``true``) or +not (``false``). It is only effective if the client doesn't use DHCP (see +`enable_dhcp`_). + + +``static_host_entries`` +~~~~~~~~~~~~~~~~~~~~~~~ + +A hash representing static host entries. The keys are the IP addresses, the +values are expected to be lists of aliases for the given IP address. Special IP +addresses like 127.0.0.1 are not allowed. diff --git a/admin-guide/puppet/profiles/nfs_server.rst b/admin-guide/puppet/profiles/nfs_server.rst new file mode 100644 index 00000000..eeec8b19 --- /dev/null +++ b/admin-guide/puppet/profiles/nfs_server.rst @@ -0,0 +1,68 @@ +``profile::nfs_server`` +======================= + +This module manages the Linux kernel NFS server and configures the exports. + +See `Implementation Notes`_ below for details. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +exports hash hiera('nfs_server::exports') +=============================== ======== ================================================ + + +``exports`` +~~~~~~~~~~~ + +A hash containing the NFS exports to be configured. The keys are the pathnames +to be exported, the values are hashes with two attributes: + +- ``options``: the default options for the export +- ``clients``: a list of hashes describing the clients + +The hashes describing the clients have two entries as well, the second one being +optional: + +- ``hosts``: a client specification as described in :manpage:`exports(5)` +- ``options`` (optional): an option string specific to these clients + +Example:: + + nfs_server::exports: + # Make software available via NFS. Installation happens + # on builder.psi.ch. + '/exports/prog': + options: 'ro,root_squash' + clients: + - hosts: '129.129.0.0/16' + - hosts: 'builder.psi.ch' + options: 'rw,no_root_squash' + # Scratch directories for prod servers. Files on scratch + # are cleaned up by a cron job on janitor.psi.ch. + '/exports/scratch': + options: 'rw,root_squash' + clients: + - hosts: '129.129.160.0/24' + - hosts: '129.129.190.0/24' + - hosts: 'janitor.psi.ch' + options: 'no_root_squash' + + +Implementation Notes +-------------------- + +We pass ``--manage-gids`` to :manpage:`rpc.mountd(8)` to avoid the following +problem. When not using Kerberos, the NFS client passes a list of groups (GIDs +really) that the user is a member of, and the server consults this list when +making access decisions. The client can pass at most 16 groups, which means that +if a user is a member of more than 16 groups, they may be denied access even +though they are a member of the necessary group. + +One solution is to use Kerberos, the other is to have the server determine group +membership itself, ignoring the client's list. The latter is what +``--manage-gids`` does. diff --git a/admin-guide/puppet/profiles/nomachine.rst b/admin-guide/puppet/profiles/nomachine.rst new file mode 100644 index 00000000..b48be1ee --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine.rst @@ -0,0 +1,45 @@ +``profile::nomachine`` +======================= + +Installs and configures a NoMachine server. i + + +This is the main class. It will configure several settings (license, service), but also +depending on the ``$nomachine_profile`` setting (defined from hiera with +``hiera('nomachine::profile')``), it will trigger different configurations according to +its profile type. + +Dependencies +------------ + +``profile::nomachine`` is invoked from the ``role::base``. In order to be able to install +NoMachine, you must setup the following setting in hiera: ``base::enable_nomachine: true`` + +Parameters +---------- + +================== =========================================== ============================= +**Name** **Type** **Default** +------------------ ------------------------------------------- ----------------------------- +$nomachine_profile Enum['desktop', 'terminal', 'workstation' ] *No default. Must be defined* +================== =========================================== ============================= + +``nomachine_profile`` +~~~~~~~~~~~~~~~~~~~~~ + +This is the NoMachine profile type. Depending on the profile type, it will call a different +sub-profile: + +- ``desktop``: + + profile::nomachine::desktop + +- ``terminal``: + + profile::nomachine::terminal + +- ``workstation``: + + profile::nomachine::workstation + +Each type contains its own specific settings and packages. diff --git a/admin-guide/puppet/profiles/nomachine/desktop.rst b/admin-guide/puppet/profiles/nomachine/desktop.rst new file mode 100644 index 00000000..aab1f245 --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine/desktop.rst @@ -0,0 +1,55 @@ +``profile::nomachine::desktop`` +=============================== + +This is a sub-class for ``profile::nomachine``. + +Installs and configures NoMachine with profile type ``desktop``. + +Dependencies +------------ + +This is part of the ``profile::nomachine``. + +Parameters +---------- + +==================================== ========= ======================================================================================================================================================================================== +**Name** **Type** **Default** +------------------------------------ --------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +$nomachine_version String ``hiera('nomachine::desktop::version')`` +$server_EnableUPnP String ``hiera('nomachine::desktop::server::EnableUPnP', 'NX')`` +$server_ConnectionsLimit Integer ``hiera('nomachine::desktop::server::ConnectionsLimit', 20)`` +$server_ConnectionsUserLimit Integer ``hiera('nomachine::desktop::server::ConnectionsUserLimit', 20)`` +$server_VirtualDesktopMode Integer ``hiera('nomachine::desktop::server::VirtualDesktopMode', 2)`` +$server_VirtualDesktopsLimit Integer ``hiera('nomachine::desktop::server::VirtualDesktopsLimit', 20)`` +$server_VirtualDesktopsUserLimit Integer ``hiera('nomachine::desktop::server::VirtualDesktopsUserLimit', 20)`` +$server_SSHAuthorizedKeys String ``hiera('nomachine::desktop::server::SSHAuthorizedKeys', 'authorized_keys')`` +$server_PhysicalDesktopAuthorization Integer ``hiera('nomachine::desktop::server::PhysicalDesktopAuthorization', 0)`` +$server_PhysicalDesktopMode Integer ``hiera('nomachine::desktop::server::PhysicalDesktopMode', 1)`` +$server_PhysicalDesktopSharing Integer ``hiera('nomachine::desktop::server::PhysicalDesktopSharing', 1)`` +$server_EnableNetworkBroadcast Integer ``hiera('nomachine::desktop::server::EnableNetworkBroadcast', 1)`` +$server_AvailableSessionTypes String ``hiera('nomachine::desktop::server::AvailableSessionTypes', 'physical-desktop,shadow')`` +$node_DefaultDesktopCommand String ``hiera('nomachine::desktop::node::DefaultDesktopCommand', '"/etc/X11/xinit/Xsession \'gnome-session --session=gnome\'"')`` +$node_AvailableSessionTypes String ``hiera('nomachine::desktop::node::AvailableSessionTypes', 'unix-remote,unix-console,unix-default,unix-application,physical-desktop,shadow,unix-xsession-default,unix-gnome,unix-xdm')`` +$node_EnableSmartcardSharing Integer ``hiera('nomachine::desktop::node::EnableSmartcardSharing', 1)`` +$node_AudioInterface String ``hiera('nomachine::desktop::node::AudioInterface', 'disabled')`` +$node_EnableCUPSSupport Integer ``hiera('nomachine::desktop::node::EnableCUPSSupport', 1)`` +$node_ClientConnectionMethods String ``hiera('nomachine::desktop::node::ClientConnectionMethods', 'NX,SSH')`` +$node_DisplayServerThreads String ``hiera('nomachine::desktop::node::DisplayServerThreads', 'auto')`` +$node_DisplayEncoderThreads String ``hiera('nomachine::desktop::node::DisplayEncoderThreads', 'auto')`` +==================================== ========= ======================================================================================================================================================================================== + +``nomachine_version`` +~~~~~~~~~~~~~~~~~~~~~ + +This parameters must be defined. Please see ``common.yaml`` for checking the default value. + +``server_*`` +~~~~~~~~~~~~ + +``$server_*`` paremeters are customizable settings for the NoMachine ``server.cfg`` configuration file. Please refer to NoMachine official documentation for more information. + +``node_*`` +~~~~~~~~~~ + +``$node_*`` paremeters are customizable settings for the NoMachine ``node.cfg`` configuration file. Please refer to NoMachine official documentation for more information. diff --git a/admin-guide/puppet/profiles/nomachine/license.rst b/admin-guide/puppet/profiles/nomachine/license.rst new file mode 100644 index 00000000..39000a1a --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine/license.rst @@ -0,0 +1,45 @@ +``profile::nomachine::license`` +=============================== + +This is a sub-class for ``profile::nomachine``. + +Installs and configures NoMachine server and node licenses to a specific directory (default ``/etc/NX``). +When licenses are updated, it triggers the activation of the new NoMachine licenses and it deploys them in ``/usr/NX/etc``. + +Dependencies +------------ + +This is part of the ``profile::nomachine``. + +Parameters +---------- + +=========================== ========== ================================================================================================ +**Name** **Type** **Default** +--------------------------- ---------- ------------------------------------------------------------------------------------------------ +$nomachine_license_location String ``hiera('nomachine::license::location', '/etc/NX')``. Defaults to ``/etc/NX`` +$nomachine_license_server String ``hiera("nomachine::license::server::$hostname")``. Must be defined and encrypyed with ``eyaml`` +$nomachine_license_node String ``hiera("nomachine::license::node::$hostname")``. Must be defined and encrypyed with ``eyaml`` +=========================== ========== ================================================================================================ + +``nomachine_license_location`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Defaults to ``/etc/NX``. Will be a temporary location for ``node.lic`` and ``server.lic``. **You must avoid to setup ``/usr/NX/etc``** +as the ``nomachine_license_location``. Can be defined in Hiera as ``nomachine::license::location``. + +``nomachine_license_server`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``eyaml`` encrypted ``server.lic``. Must be defined in hiera as ``nomachine::license::server::$hostname``, where ``$hostname`` is the +host shortname of the NoMachine server (equivalent to run ``hostname -s`` from command line). + +For more information about encryption with ``eyaml``, please refer to http://linux-infra.gitpages.psi.ch/admin-guide/puppet/hiera.html#secret-values + +``nomachine_license_node`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``eyaml`` encrypted ``node.lic``. Must be defined in hiera as ``nomachine::license::node::$hostname``, where ``$hostname`` is the +host shortname of the NoMachine server (equivalent to run ``hostname -s`` from command line). + +For more information about encryption with ``eyaml``, please refer to http://linux-infra.gitpages.psi.ch/admin-guide/puppet/hiera.html#secret-values diff --git a/admin-guide/puppet/profiles/nomachine/repository.rst b/admin-guide/puppet/profiles/nomachine/repository.rst new file mode 100644 index 00000000..5d0e6daa --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine/repository.rst @@ -0,0 +1,20 @@ +``profile::nomachine::repository`` +================================== + +This is a sub-class for ``profile::nomachine``. + +This class just installs and configures a NoMachine repository. Is a very basic class with +no configurable options. + +Dependencies +------------ + +This is part of the ``profile::nomachine``. + +Parameters +---------- + +================== =========================================== ============================= +**Name** **Type** **Default** +------------------ ------------------------------------------- ----------------------------- +================== =========================================== ============================= diff --git a/admin-guide/puppet/profiles/nomachine/service.rst b/admin-guide/puppet/profiles/nomachine/service.rst new file mode 100644 index 00000000..630213c5 --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine/service.rst @@ -0,0 +1,20 @@ +``profile::nomachine::service`` +=============================== + +This is a sub-class for ``profile::nomachine``. + +This class just installs and configures a NoMachine service. Is a very basic class with +no configurable options. + +Dependencies +------------ + +This is part of the ``profile::nomachine``. + +Parameters +---------- + +================== =========================================== ============================= +**Name** **Type** **Default** +------------------ ------------------------------------------- ----------------------------- +================== =========================================== ============================= diff --git a/admin-guide/puppet/profiles/nomachine/terminal.rst b/admin-guide/puppet/profiles/nomachine/terminal.rst new file mode 100644 index 00000000..5feed416 --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine/terminal.rst @@ -0,0 +1,56 @@ +``profile::nomachine::terminal`` +================================ + +This is a sub-class for ``profile::nomachine``. + +Installs and configures NoMachine with profile type ``terminal``. + +Dependencies +------------ + +This is part of the ``profile::nomachine``. + +Parameters +---------- + +==================================== ========= =========================================================================================================================================================================================== +**Name** **Type** **Default** +------------------------------------ --------- ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +$nomachine_version String ``hiera('nomachine::terminal::version')``. This is mandatory. See ``common.yaml`` for default value. +$server_EnableUPnP String ``hiera('nomachine::terminal::server::EnableUPnP', 'none')`` +$server_ConnectionsLimit Integer ``hiera('nomachine::terminal::server::ConnectionsLimit', 200)`` +$server_ConnectionsUserLimit Integer ``hiera('nomachine::terminal::server::ConnectionsUserLimit', 2)`` +$server_DisconnectedSessionExpiry Integer ``hiera('nomachine::terminal::server::DisconnectedSessionExpiry', 0)`` +$server_VirtualDesktopMode Integer ``hiera('nomachine::terminal::server::VirtualDesktopMode', 0)`` +$server_VirtualDesktopsLimit Integer ``hiera('nomachine::terminal::server::VirtualDesktopsLimit', 300)`` +$server_VirtualDesktopsUserLimit Integer ``hiera('nomachine::terminal::server::VirtualDesktopsUserLimit', 2)`` +$server_SSHAuthorizedKeys String ``hiera('nomachine::terminal::server::SSHAuthorizedKeys', 'authorized_keys')`` +$server_PhysicalDesktopAuthorization Integer ``hiera('nomachine::terminal::server::PhysicalDesktopAuthorization', 1)`` +$server_PhysicalDesktopMode Integer ``hiera('nomachine::terminal::server::PhysicalDesktopMode', 2)`` +$server_PhysicalDesktopSharing Integer ``hiera('nomachine::terminal::server::PhysicalDesktopSharing', 0)`` +$server_EnableNetworkBroadcast Integer ``hiera('nomachine::terminal::server::EnableNetworkBroadcast', 0)`` +$server_AvailableSessionTypes String ``hiera('nomachine::terminal::server::AvailableSessionTypes', 'unix-remote,unix-console,unix-default,unix-application,physical-desktop,shadow,unix-xsession-default,unix-gnome,unix-xdm')`` +$node_DefaultDesktopCommand String ``hiera('nomachine::terminal::node::DefaultDesktopCommand', '"/etc/X11/xinit/Xsession \'gnome-session --session=gnome\'"')`` +$node_AvailableSessionTypes String ``hiera('nomachine::terminal::node::AvailableSessionTypes', 'unix-remote,unix-console,unix-default,unix-application,physical-desktop,shadow,unix-xsession-default,unix-gnome,unix-xdm')`` +$node_EnableSmartcardSharing Integer ``hiera('nomachine::terminal::node::EnableSmartcardSharing', 1)`` +$node_AudioInterface String ``hiera('nomachine::terminal::node::AudioInterface', 'disabled')`` +$node_EnableCUPSSupport Integer ``hiera('nomachine::terminal::node::EnableCUPSSupport', 1)`` +$node_ClientConnectionMethods String ``hiera('nomachine::terminal::node::ClientConnectionMethods', 'NX,SSH')`` +$node_DisplayServerThreads String ``hiera('nomachine::terminal::node::DisplayServerThreads', 'auto')`` +$node_DisplayEncoderThreads String ``hiera('nomachine::terminal::node::DisplayEncoderThreads', 'auto')`` +==================================== ========= =========================================================================================================================================================================================== + +``nomachine_version`` +~~~~~~~~~~~~~~~~~~~~~ + +This parameters must be defined. Please see ``common.yaml`` for checking the default value. + +``server_*`` +~~~~~~~~~~~~ + +``$server_*`` paremeters are customizable settings for the NoMachine ``server.cfg`` configuration file. Please refer to NoMachine official documentation for more information. + +``node_*`` +~~~~~~~~~~ + +``$node_*`` paremeters are customizable settings for the NoMachine ``node.cfg`` configuration file. Please refer to NoMachine official documentation for more information. diff --git a/admin-guide/puppet/profiles/nomachine/workstation.rst b/admin-guide/puppet/profiles/nomachine/workstation.rst new file mode 100644 index 00000000..6e876c1a --- /dev/null +++ b/admin-guide/puppet/profiles/nomachine/workstation.rst @@ -0,0 +1,56 @@ +``profile::nomachine::workstation`` +=================================== + +This is a sub-class for ``profile::nomachine``. + +Installs and configures NoMachine with profile type ``workstation``. + +Dependencies +------------ + +This is part of the ``profile::nomachine``. + +Parameters +---------- + +==================================== ========= =============================================================================================================================== +**Name** **Type** **Default** +------------------------------------ --------- ------------------------------------------------------------------------------------------------------------------------------- +$nomachine_version String ``hiera('nomachine::workstation::version')`` +$server_EnableUPnP String ``hiera('nomachine::workstation::server::EnableUPnP', 'NX')`` +$server_ConnectionsLimit Integer ``hiera('nomachine::workstation::server::ConnectionsLimit', 20)`` +$server_ConnectionsUserLimit Integer ``hiera('nomachine::workstation::server::ConnectionsUserLimit', 20)`` +$server_VirtualDesktopMode Integer ``hiera('nomachine::workstation::server::VirtualDesktopMode', 2)`` +$server_VirtualDesktopsLimit Integer ``hiera('nomachine::workstation::server::VirtualDesktopsLimit', 20)`` +$server_VirtualDesktopsUserLimit Integer ``hiera('nomachine::workstation::server::VirtualDesktopsUserLimit', 20)`` +$server_SSHAuthorizedKeys String ``hiera('nomachine::workstation::server::SSHAuthorizedKeys', 'authorized_keys')`` +$server_PhysicalDesktopAuthorization Integer ``hiera('nomachine::workstation::server::PhysicalDesktopAuthorization', 0)`` +$server_PhysicalDesktopMode Integer ``hiera('nomachine::workstation::server::PhysicalDesktopMode', 1)`` +$server_PhysicalDesktopSharing Integer ``hiera('nomachine::workstation::server::PhysicalDesktopSharing', 2)`` +$server_EnableNetworkBroadcast Integer ``hiera('nomachine::workstation::server::EnableNetworkBroadcast', 1)`` +$server_AvailableSessionTypes String ``hiera('nomachine::workstation::server::AvailableSessionTypes', 'shadow,unix-xsession-default')`` +$node_DefaultDesktopCommand String ``hiera('nomachine::workstation::node::DefaultDesktopCommand', '"/etc/X11/xinit/Xsession \'gnome-session --session=gnome\'"')`` +$node_AvailableSessionTypes String ``hiera('nomachine::workstation::node::AvailableSessionTypes', 'shadow,unix-xsession-default')`` +$node_EnableSmartcardSharing Integer ``hiera('nomachine::workstation::node::EnableSmartcardSharing', 1)`` +$node_AudioInterface String ``hiera('nomachine::workstation::node::AudioInterface', 'disabled')`` +$node_EnableCUPSSupport Integer ``hiera('nomachine::workstation::node::EnableCUPSSupport', 1)`` +$node_ClientConnectionMethods String ``hiera('nomachine::workstation::node::ClientConnectionMethods', 'NX,SSH')`` +$node_DisplayServerThreads String ``hiera('nomachine::workstation::node::DisplayServerThreads', 'auto')`` +$node_DisplayEncoderThreads String ``hiera('nomachine::workstation::node::DisplayEncoderThreads', 'auto')`` +==================================== ========= =============================================================================================================================== + +``nomachine_version`` +~~~~~~~~~~~~~~~~~~~~~ + +This parameters must be defined. Please see ``common.yaml`` for checking the default value. + + +``server_*`` +~~~~~~~~~~~~ + +``$server_*`` paremeters are customizable settings for the NoMachine ``server.cfg`` configuration file. Please refer to NoMachine official documentation for more information. + +``node_*`` +~~~~~~~~~~ + +``$node_*`` paremeters are customizable settings for the NoMachine ``node.cfg`` configuration file. Please refer to NoMachine official documentation for more information. diff --git a/admin-guide/puppet/profiles/ntp_client.rst b/admin-guide/puppet/profiles/ntp_client.rst new file mode 100644 index 00000000..32d07702 --- /dev/null +++ b/admin-guide/puppet/profiles/ntp_client.rst @@ -0,0 +1,32 @@ +``profile::ntp_client`` +======================= + +This module configures the NTP client to synchronize the local system time with +a number of time servers. Queries by other systems are disabled for security +reasons. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +servers hash hiera_hash('ntp_client::servers') +=============================== ======== ================================================ + + +``servers`` +~~~~~~~~~~~ + +A hash containing the list of NTP servers for each :doc:`network zone +<../profiles/networking>`, eg.:: + + ntp_client::servers: + 'default': + - 'pstime1.psi.ch' + - 'pstime2.psi.ch' + - 'pstime3.psi.ch' + 'dmz': + - 'dmztime1.psi.ch' + - 'dmztime2.psi.ch' diff --git a/admin-guide/puppet/profiles/nvidia.rst b/admin-guide/puppet/profiles/nvidia.rst new file mode 100644 index 00000000..0a2abce2 --- /dev/null +++ b/admin-guide/puppet/profiles/nvidia.rst @@ -0,0 +1,40 @@ +``profile::nvidia`` +=================== + +The purpose of this module is to install the NVIDIA drivers. If NVIDIA GPU cards are +detected with the facter ``pci_devices.gpu.nvidia``, automatically the ``profile::nvidia`` +class will be called. The ``class profile::platform`` is responsible for calling this profile:: + + if ( $facts['pci_devices']['gpu']['nvidia'].size > 0 ) { + class { 'profile::nvidia':; } + } + +Current profile only installs drivers using the CUDA installation. Other NVIDIA installations +(i.e. just NVIDIA drivers for Desktops without CUDA) are still not implemented. + +To enable CUDA installation ``nvidia::cuda::enable`` must be set to ``true`` (default +is ``false``). When this setting is set to ``false`` (default), NVIDIA installation without +CUDA should be performed (as already specified, this is not implemented yet) + +Parameters +---------- + +================= ========== =========== +**Name** **Type** **Default** +----------------- ---------- ----------- +cuda_version string 8-0 +cuda_enable bool false +================= ========== =========== + + +``cuda_version`` +~~~~~~~~~~~~~~~~ + +By default ``8-0`` is the version for the CUDA metapackage. To make installation possible, +``cuda_enable`` must be also set up. + +``cuda_enable`` +~~~~~~~~~~~~~~~ + +By default is ``false``. Set to ``true`` if you want to install CUDA and NVIDIA drivers from +the CUDA repositories. diff --git a/admin-guide/puppet/profiles/platform.rst b/admin-guide/puppet/profiles/platform.rst new file mode 100644 index 00000000..833f7c40 --- /dev/null +++ b/admin-guide/puppet/profiles/platform.rst @@ -0,0 +1,47 @@ +``profile::platform`` +===================== + +The purpose of this ``profile`` is to install specific components depending on the hardware components +and hardware/platform type. + +Currently, for ``vmware`` machines no actions are performed. For ``physical`` machines some actions will +be performed depending on the parameter settings (see below). + +Also, according to the facter ``manufacturer``, some specific actions can be triggered. Currently only +``HP``/``HPE`` hardware is considered. + +Other options such like NVIDIA or Infiniband card detection are possible. Whenever detected, it will call +the corresponding class and will perform required actions. + +Parameters +---------- + +================= ========== =========== +**Name** **Type** **Default** +----------------- ---------- ----------- +enable_rasdaemon bool +enable_smartd bool +================= ========== =========== + +``enable_rasdaemon`` +~~~~~~~~~~~~~~~~~~~~ + +When set to ``true``, will install and enable the ``rasdaemon`` service. + +``enable_smartd`` +~~~~~~~~~~~~~~~~~ + +When set to ``true``, will install and enable the ``smartmontools`` (``smartd``) service. + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +===================================== =============== ============================================== +**Fact** **Value(s)** **Action description** +------------------------------------- --------------- ---------------------------------------------- +``manufacturer`` ``HP``|``HPE`` ``include profile::platform::hewlett_packard`` +``['pci_devices']['gpu']['nvidia']`` count > 0 ``include profile::nvidia`` +``['pci_devices']['ib']['mellanox']`` count > 0 ``include profile::infiniband`` +===================================== =============== ============================================== diff --git a/admin-guide/puppet/profiles/platform/hewlett_packard.rst b/admin-guide/puppet/profiles/platform/hewlett_packard.rst new file mode 100644 index 00000000..af4215be --- /dev/null +++ b/admin-guide/puppet/profiles/platform/hewlett_packard.rst @@ -0,0 +1,24 @@ +``profile::platform::hewlett_packard`` +====================================== + +When ``profile::platform::hewlett_packard`` is called (usually from the ``profile::platform`` through +the facter ``manufacturer``, by auto-detecting an HP platform) some actions will be triggered. + +Parameters +---------- + +================= ========== =========== +**Name** **Type** **Default** +----------------- ---------- ----------- +================= ========== =========== + +Facts +----- + +When some specific facts are detected, it will trigger some actions. + +==================================== ================= ======================================================= +**Fact** **Value(s)** **Action description** +------------------------------------ ----------------- ------------------------------------------------------- +``productname`` ``/^ProLiant.*/`` Install ``hpssacli`` for HP Array Management/Monitoring +==================================== ================= ======================================================= diff --git a/admin-guide/puppet/profiles/pmodules.rst b/admin-guide/puppet/profiles/pmodules.rst new file mode 100644 index 00000000..0cfdaafb --- /dev/null +++ b/admin-guide/puppet/profiles/pmodules.rst @@ -0,0 +1,54 @@ +``profile::pmodules`` +===================== + +This module manages the `AIT Pmodules +`_. + +It automatically enables Pmodules for all users with + +1. a UID >= 1000 +2. a username **not** ending in ``-adm`` + +This makes sure that local service accounts, root, and administrator accounts do +not use Pmodules automatically. + + +Parameters +---------- + +================== ======== ============================== +**Name** **Type** **Default** +------------------ -------- ------------------------------ +basedir string hiera('pmodules::basedir') +================== ======== ============================== + + +``basedir`` +~~~~~~~~~~~ + +The subdirectory of ``/afs/psi.ch/sys/`` where the modules can be found, e.g. +``psi.x86_64_slp6`` or ``psi.ra``. + + +Examples +-------- + +This profile is included in the base role, but disabled. To enable Pmodules +simply pass ``enable_pmodules => true`` when including the base role:: + + class role::some_role () { + class {'role::base': + enable_pmodules => true, + ... + } + ... + +To customize the base directory, include ``pmodules`` separately:: + + class role::some_role () { + include role::base + + class {'profile::pmodules': + basedir => 'psi.ra', + } + ... diff --git a/admin-guide/puppet/profiles/print_client.rst b/admin-guide/puppet/profiles/print_client.rst new file mode 100644 index 00000000..adf3d465 --- /dev/null +++ b/admin-guide/puppet/profiles/print_client.rst @@ -0,0 +1,29 @@ +``profile::print_client`` +========================= + +This module configures printing to the PSI print server. + +Currently, CUPS is used. + + +Parameters +---------- + +=============================== ======== ======================================= +**Name** **Type** **Default** +------------------------------- -------- --------------------------------------- +default_printer string hiera('print_client::default_printer') +print_server string hiera('print_client::server') +=============================== ======== ======================================= + + +``default_printer`` +~~~~~~~~~~~~~~~~~~~ + +The default printer to be configured in the PRINTER environment variable. + + +``print_server`` +~~~~~~~~~~~~~~~~ + +The FQDN of the CUPS print server to use. diff --git a/admin-guide/puppet/profiles/puppet_client.rst b/admin-guide/puppet/profiles/puppet_client.rst new file mode 100644 index 00000000..6bd504c6 --- /dev/null +++ b/admin-guide/puppet/profiles/puppet_client.rst @@ -0,0 +1,23 @@ +``profile::puppet_client`` +========================== + + +Parameters +---------- + +========== ========= ========================= +**Name** **Type** **Default** +---------- --------- ------------------------- +exec_time string ``05:00:00 -- 08:00:00`` +========== ========= ========================= + + +``exec_time`` +~~~~~~~~~~~~~ + +Defines a time window during which Puppet will run every day. The exact time +depends on the FQDN of the system (see below), ensuring that on each system the +timing is consistent and predictable, but across a group of systems using the +same time window the exact times are distributed uniformly. + +The syntax is ``HH:MM:SS -- HH:MM:SS``. diff --git a/admin-guide/puppet/profiles/serial_console.rst b/admin-guide/puppet/profiles/serial_console.rst new file mode 100644 index 00000000..01f7221d --- /dev/null +++ b/admin-guide/puppet/profiles/serial_console.rst @@ -0,0 +1,27 @@ +``profile::serial_console`` +=========================== + +Configures the serial console on physical systems. + + +Parameters +---------- + +========= ========= ============ +**Name** **Type** **Default** +--------- --------- ------------ +device string ``ttyS0`` +rate integer 115200 +========= ========= ============ + + +``device`` +~~~~~~~~~~ + +The device to configure as a console. + + +``rate`` +~~~~~~~~ + +The rate to use for the serial console. diff --git a/admin-guide/puppet/profiles/ssh_client.rst b/admin-guide/puppet/profiles/ssh_client.rst new file mode 100644 index 00000000..ce1a4ff7 --- /dev/null +++ b/admin-guide/puppet/profiles/ssh_client.rst @@ -0,0 +1,38 @@ +``profile::ssh_client`` +======================= + +This profile configures '/etc/ssh/ssh_known_hosts' :manpage:`sshd(8)`. +PSI CA key is added to the 'ssh_known_hosts', in this manner we allow +PSI servers to SSH to this host. + + +Parameters +---------- + +====================== ======== ============================================= +**Name** **Type** **Default** +---------------------- -------- --------------------------------------------- +allowed_hosts string '\*.psi.ch' +canonicalize_hostname bool false +forward_x11 bool +====================== ======== ============================================= + + +``allowed_hosts`` +~~~~~~~~~~~~~~~~~ + +A string specifying which hosts are allowed to SSH to this machine. By default, +all PSI hosts will be able to connect. + + +``canonicalize_hostname`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Determines whether or not hostnames are canonicalized for ``psi.ch``. See +:manpage:`ssh_config(5)` for details. + + +``foward_x11`` +~~~~~~~~~~~~~~ + +Determines whether ``ForwardX11`` and ``ForwardX11Trusted`` should be enabled. diff --git a/admin-guide/puppet/profiles/ssh_server.rst b/admin-guide/puppet/profiles/ssh_server.rst new file mode 100644 index 00000000..6c229cad --- /dev/null +++ b/admin-guide/puppet/profiles/ssh_server.rst @@ -0,0 +1,42 @@ +``profile::ssh_server`` +======================= + +This profile configures :manpage:`sshd(8)`. + + +Parameters +---------- + +==================== ======== ============================================= +**Name** **Type** **Default** +-------------------- -------- --------------------------------------------- +enable_gssapi bool hiera('ssh_server::enable_gssapi') +permit_root_login string hiera('ssh_server::permit_root_login') +trusted_user_ca_keys list hiera('ssh_server::trusted_user_ca_keys', []) +user_ca_keys hash hiera('ssh_server::user_ca_keys', {}) +==================== ======== ============================================= + + +``enable_gssapi`` +~~~~~~~~~~~~~~~~~ + +A boolean determining whether GSSAPI authentication is enabled or not. + + +``permit_root_login`` +~~~~~~~~~~~~~~~~~~~~~ + +Sets ``PermitRootLogin`` in the sshd configuration file. + + +``trusted_user_ca_keys`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +An array containing the user CA keys that will be accepted (as understood by the +``TrustedUserCAKeys`` directive in :manpage:`sshd_config(5)`). + + +``user_ca_keys`` +~~~~~~~~~~~~~~~~ + +A hash containing the actual keys to be referenced by `trusted_user_ca_keys`_. diff --git a/admin-guide/puppet/profiles/sysinfo.rst b/admin-guide/puppet/profiles/sysinfo.rst new file mode 100644 index 00000000..ea326703 --- /dev/null +++ b/admin-guide/puppet/profiles/sysinfo.rst @@ -0,0 +1,10 @@ +``profile::sysinfo`` +==================== + +Stores certain information about the system in ``/etc/sysconfig/pli-info`` for +the use of other programs and scripts. Currently, the following values are +stored: + +- ``SYSDB_ENV``: the system's sysdb environment +- ``PUPPET_GROUP``: the system's ``puppet_group`` value from sysdb +- ``PUPPET_ROLE``: the system's ``puppet_role`` value from sysdb diff --git a/admin-guide/puppet/profiles/telegraf.rst b/admin-guide/puppet/profiles/telegraf.rst new file mode 100644 index 00000000..109c517e --- /dev/null +++ b/admin-guide/puppet/profiles/telegraf.rst @@ -0,0 +1,58 @@ +``profile::telegraf`` +===================== + +This profile configures the `telegraf +`_ metrics collection +agent. + + +Parameters +---------- + +=============================== ======== ================================================ +**Name** **Type** **Default** +------------------------------- -------- ------------------------------------------------ +enable_service bool +agent hash hiera_hash('telegraf::agent') +metrics hash lookup('telegraf::metrics', {merge => 'deep'}) +=============================== ======== ================================================ + + +``enable_service`` +~~~~~~~~~~~~~~~~~~ + +Determines whether or not Puppet will start or stop the service. + + +``agent`` +~~~~~~~~~ + +This hash can be used to set the following configuration options in +``/etc/telegraf/telegraf.conf``: + + - ``metric_buffer_limit`` + - ``collection_jitter`` + - ``flush_interval`` + - ``flush_jitter`` + - ``urls`` + + +``metrics`` +~~~~~~~~~~~ + +This hash defines the metrics which the telegraf agent will collect. The keys +are the names of the metrics and the values are hashes describing the metric. +Every key/value pair in these hashes will be added to the configuration files +directly without any checks. + +Examples:: + + 'cpu': + enable: true + 'disk': + enable: true + interval: '30m' + ignore_fs: + - 'aufs' + - 'auristorfs' + - 'devfs' diff --git a/admin-guide/puppet/profiles/web_server.rst b/admin-guide/puppet/profiles/web_server.rst new file mode 100644 index 00000000..ec10e68a --- /dev/null +++ b/admin-guide/puppet/profiles/web_server.rst @@ -0,0 +1,49 @@ +``profile::web_server`` +======================= + +Install and configure Apache to make local files available through HTTP/HTTPS. + + +Parameters +---------- + +========== ========= ============ +**Name** **Type** **Default** +---------- --------- ------------ +tls_cert string +tls_chain string +tls_key string +vhost string +url_map hash +========== ========= ============ + +``tls_cert`` +~~~~~~~~~~~~ + +The TLS certificate (PEM). + + +``tls_chain`` +~~~~~~~~~~~~~ + +The TLS certificate chain, ie. the intermediate certificate concatenated with +the host's certificate. + + +``tls_key`` +~~~~~~~~~~~ + +The TLS key (PEM). **Must be encrypted**! + + +``vhost`` +~~~~~~~~~ + +The name of the Apache virtual host, eg. ``linux.web.psi.ch``. + + +``url_map`` +~~~~~~~~~~~ + +A hash describing the mapping between URLs and files. The keys are the URLs +relative to the `vhost`_, the values are the corresponding paths. diff --git a/admin-guide/puppet/profiles/yum_client.rst b/admin-guide/puppet/profiles/yum_client.rst new file mode 100644 index 00000000..a0b803b5 --- /dev/null +++ b/admin-guide/puppet/profiles/yum_client.rst @@ -0,0 +1,55 @@ +``profile::yum_client`` +======================= + +This module configures :manpage:`yum(8)`. + + +Parameters +---------- + +=============================== ======== ============================================= +**Name** **Type** **Default** +------------------------------- -------- --------------------------------------------- +exclude list hiera('yum_client::exclude', []) +package_groups list hiera_array('yum_client::package_groups', []) +purge_repositories bool hiera('yum_client::purge_repositories') +repos list hiera_array('yum_client::repositories') +=============================== ======== ============================================= + + +``exclude`` +~~~~~~~~~~~ + +An array containing entries suitable for the ``exclude`` option in +:manpage:`yum.conf(5)`. + + +``package_group`` +~~~~~~~~~~~~~~~~~ + +A list containing the names of the package groups to be installed on the +systems. The package groups have to be defined through `pkg_group::$NAME`_ and +are completely independent of Yum (environment) groups. + + +``pkg_group::$NAME`` +~~~~~~~~~~~~~~~~~~~~ + +The list of packages that comprise the package group ``$NAME``. + + +``purge_repositories`` +~~~~~~~~~~~~~~~~~~~~~~ + +A boolean controlling whether files that were not created by Puppet should be +removed from ``/etc/yum.repos.d``. This is useful to prevent repositories to be +configured through other means (e.g. manually). + + +``repos`` +~~~~~~~~~ + +A list of names designating the repositories that are to be configured (not +necessarily enabled) on the system. If ```` is the name of the repository, +then its definition is determined by searching Hiera for the +``yum_client::repo_`` key. diff --git a/admin-guide/puppet/puppet-master.rst b/admin-guide/puppet/puppet-master.rst new file mode 100644 index 00000000..05363b05 --- /dev/null +++ b/admin-guide/puppet/puppet-master.rst @@ -0,0 +1,37 @@ +Puppet Master +============= + +Installation +------------ + +Installation of a puppet master is in some way more difficult than all +the other system, since no pre-existant infrastructure is supposed to +be present. It comes natural that the Puppet master is the first +server to be deployed in the current infrastructure. + +This `Git repository `_ +contains the code to deploy a new puppet master. + +The procedure to install it are the following steps: + +1. install the server, using ``puppet master`` as profile. See `this `_ for more informations; + +2. after the server reboot, you are be able to login with your `authorized ssh key `_; + +3. copy the ssh root key to the right location with the right + permissions, so that the server is able to authenticate itself + against the git repository: :: + + PUPPETMMASTER=puppetmaster.psi.ch + scp ssh_rsa_key* root@$PUPPETMASTER:/root/.ssh + ssh root@$PUPPETMASTER + chmod 400 /etc/ssh/ssh_rsa_key + chmod 444 /etc/ssh/ssh_rsa_key.pub + +4. You can now deploy the puppet server with the following code: :: + + git clone https://git.psi.ch/linux-infra/bootstrap + cd bootstrap/instcode + ./puppetmaster.sh + + diff --git a/admin-guide/puppet/puppet_workflow.jpg b/admin-guide/puppet/puppet_workflow.jpg new file mode 100644 index 00000000..b5c31a22 Binary files /dev/null and b/admin-guide/puppet/puppet_workflow.jpg differ diff --git a/admin-guide/puppet/roles/base.rst b/admin-guide/puppet/roles/base.rst new file mode 100644 index 00000000..9134a36e --- /dev/null +++ b/admin-guide/puppet/roles/base.rst @@ -0,0 +1,264 @@ +``role::base`` +============== + +This role is special in that **it cannot be assigned to a system**. It is meant +to be included by all other roles and provide basic functionality that all roles +need anyway. + + +Parameters +---------- + +====================== ======== ================================================ +**Name** **Type** **Default** +---------------------- -------- ------------------------------------------------ +default_target string ``multi-user`` +enable_afs bool false +enable_autofs bool false +enable_filecopy bool hiera('base::enable_filecopy') +enable_ganglia bool false +enable_icinga bool true +enable_kdump_client bool true +enable_multipath bool hiera('base::enable_multipath') +enable_nfs_server bool false +enable_nomachine bool hiera('base::enable_nomachine') +enable_platform bool hiera('base::enable_platform') +enable_pmodules bool false +enable_print_client bool false +enable_rhgb bool false +enable_sensu bool hiera('base::enable_sensu') +enable_ssh_client bool hiera('base::enable_ssh_client') +enable_telegraf bool hiera('base::enable_telegraf') +enable_updatedb bool true +include_aaa bool true +include_log_client bool true +include_yum_client bool true +package_groups array [] +pkg_group::* array - +selinux_mode string ``enforcing`` +====================== ======== ================================================ + + +``default_target`` +~~~~~~~~~~~~~~~~~~ + +Specifies the systemd default target to configure. This does not *isolate* the +target (see :manpage:`systemctl(1)`), but merely sets it so it will become +active after a reboot. + + +``enable_afs`` +~~~~~~~~~~~~~~ + +Determines whether to include the :doc:`afs_client <../profiles/afs_client>` +profile. + + +``enable_autofs`` +~~~~~~~~~~~~~~~~~ + +Enable the ``autofs`` service. This is **not** needed for automounts! It is only +needed to support the ``-hosts`` map as documented in :manpage:`auto.master`. +The ``-hosts`` map is mounted on ``/net``. + + +``enable_filecopy`` +~~~~~~~~~~~~~~~~~~~ + +Enable the ``filecopy`` profile, which allows deploying arbitrary files from +``git.psi.ch`` through Hiera. + + +``enable_ganglia`` +~~~~~~~~~~~~~~~~~~ + +Determines whether to include the :doc:`ganglia_client +<../profiles/ganglia_client>`. + + + +``enable_sensu`` +~~~~~~~~~~~~~~~~ + +Enable the Sensu client and checks. + + +``enable_ssh_client`` +~~~~~~~~~~~~~~~~~~~~~ + +Deploy global SSH client configuration, ie ``/etc/ssh/ssh_config``. + + +``enable_telegraf`` +~~~~~~~~~~~~~~~~~~~ + +Enable the telegraf monitoring agent, which reports various system metrics to +InfluxDB servers. + + +``enable_icinga`` +~~~~~~~~~~~~~~~~~ + +Determines whether to include the :doc:`icinga_client +<../profiles/icinga_client>` profile, which installs the client components +necessary for Icinga-based monitoring. + + +``enable_kdump_client`` +~~~~~~~~~~~~~~~~~~~~~~~ + +Determines whether to include the :doc:`kdump_client <../profiles/kdump_client>` +profile. + + +``enable_multipath`` +~~~~~~~~~~~~~~~~~~~~ + +Enable the ``multipath`` profile for basic multipath functionality. + + +``enable_nfs_server`` +~~~~~~~~~~~~~~~~~~~~~ + +Enable the kernel NFS server and configure the :manpage:`exports(5)` file. See +the :doc:`nfs_server <../profiles/nfs_server>` profile for details. + + +``enable_nomachine`` +~~~~~~~~~~~~~~~~~~~~ + +Include the ``nomachine`` profile, which can install NoMachine NX in various +configurations. + + +``enable_platform`` +~~~~~~~~~~~~~~~~~~~ + +Enable the ``platform`` profile, which installs and configures hardware-specific +tools and configurations. + + +``enable_pmodules`` +~~~~~~~~~~~~~~~~~~~ + +Determines whether to enable the :doc:`pmodules <../profiles/pmodules>` profile. +When true, the necessary configuration is automatically sourced for all normal +users (ie UID >= 1000 and no ``-adm`` suffix) using :manpage:`bash(1)`. + +Requires AFS to work, as the required configuration files are stored on AFS. + + +``enable_print_client`` +~~~~~~~~~~~~~~~~~~~~~~~ + +Enable and configure CUPS as a client. See the :doc:`print_client +<../profiles/print_client>` profile for details. + + +``enable_rhgb`` +~~~~~~~~~~~~~~~ + +Determines whether the graphical boot screen is enabled. + + +``enable_updatedb`` +~~~~~~~~~~~~~~~~~~~ + +Determines whether or not :manpage:`updatedb(8)` (aka :manpage:`locate(1)`) is +enabled or not. When enabled, it is still possible to exclude certain +directories for indexing. This is also supported directly by the mounter module. + + +``include_aaa`` +~~~~~~~~~~~~~~~ + +Determines whether to include the :doc:`aaa <../profiles/aaa>` profile, which +configures authentication, authorization, and (partly) auditing. + + +``include_log_client`` +~~~~~~~~~~~~~~~~~~~~~~ + +Include the :doc:`log_client <../profiles/log_client>` profile. This is only +meant to allow roles customization of the :doc:`log_client +<../profiles/log_client>` profile. + + +``include_yum_client`` +~~~~~~~~~~~~~~~~~~~~~~ + +Determines whether to include the :doc:`yum_client <../profiles/yum_client>` +profile. + + +``package_groups`` +~~~~~~~~~~~~~~~~~~ + +The list of package groups to install. Package groups are defined using +`pkg_group::NAME`_. + + +``pkg_group::NAME`` +~~~~~~~~~~~~~~~~~~~ + +An array defining the package group ``NAME``. Package groups are installed using +the `package_groups`_ parameter. + + +``selinux_mode`` +~~~~~~~~~~~~~~~~ + +The SELinux mode to use, one of ``enforcing``, ``permissive``, and ``disabled``. +The *configured* SELinux mode (ie the setting in ``/etc/sysconfig/selinux``) is +changed immediately. The runtime mode is changed as follows, as certain +transitions are impossible without a reboot: + +========== ========== =========== +Current Setting New runtime +---------- ---------- ----------- +Enforcing Disabled Permissive +Enforcing Permissive Permissive +Permissive Enforcing Enforcing +Permissive Disabled Permissive +Disabled Permissive Disabled +Disabled Enforcing Disabled +========== ========== =========== + + +Examples +-------- + +The most basic usage is:: + + class role::some_role () { + + include role::base + + ... + } + +Most profiles that are included can be excluded when necessary:: + + class role::some_role () { + + class {'role::base': + include_icinga => false, + } + + ... + } + +This can be used to customize some of the basic profiles:: + + class role::base () { + + class {'role::base': + include_aaa => false, + } + + class {'profile::aaa': + allow_sudoers_d => true, + } + + ... + } diff --git a/admin-guide/puppet/roles/bootpc.rst b/admin-guide/puppet/roles/bootpc.rst new file mode 100644 index 00000000..d3847193 --- /dev/null +++ b/admin-guide/puppet/roles/bootpc.rst @@ -0,0 +1,16 @@ +``role::bootpc`` +================ + +This role implements a GFA bootpc system. + + +Parameters +---------- + +``yum_client::pkg_group::bootpc`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The package group ``bootpc`` is *always* installed by this role. Other roles +usually ignore it, but of course it can be installed on such systems using the +``yum_client::package_groups`` parameter. See the :doc:`yum_client +<../profiles/yum_client>` documentation for details. diff --git a/admin-guide/puppet/roles/console.rst b/admin-guide/puppet/roles/console.rst new file mode 100644 index 00000000..d4f5dfb6 --- /dev/null +++ b/admin-guide/puppet/roles/console.rst @@ -0,0 +1,82 @@ +``role::console`` +================= + +A console as used at SLS/SwissFEL/... beamlines. Essentially a workstation with +additional configuration for Epics, mounts, etc. + + +Parameters +---------- + +================= ========= ============== +**Name** **Type** **Default** +----------------- --------- -------------- +banner_message string See ``common.yaml`` +favorites array See ``common.yaml`` +keyboard_layouts array See ``common.yaml`` +local_homes bool false +mount_root string +mounts array +priv_users array +symlink_root string +users array +================= ========= ============== + + +``banner_message`` +~~~~~~~~~~~~~~~~~~ + +A message displayed on the login screen. + + +``favorites`` +~~~~~~~~~~~~~ + +The of applications/locations in the 'Favorites' menu. Entries usually specify +an application's desktop file, eg. 'firefox.desktop'. + + +``keyboard_layouts`` +~~~~~~~~~~~~~~~~~~~~ + +The list of keyboard layouts available on the login screen. + + +``local_homes`` +~~~~~~~~~~~~~~~ + +Whether or not to use local homes in ``/home``. + + +``mount_root`` +~~~~~~~~~~~~~~ + +The directory where the mountpoint for the mounts in `mounts`_ are created. + + +``mounts`` +~~~~~~~~~~ + +A list of mounts defined through ``mounter::def::NAME`` (see the :doc:`mounter +<../profiles/mounter>`). The mounts must have a mountpoint beneath `mount_root`_ +for `symlink_root`_ to work properly. + + +``priv_users`` +~~~~~~~~~~~~~~ + +A list of users, which will have admin privileges in the UI. They can install +additional software, for example. + + +``symlink_root`` +~~~~~~~~~~~~~~~~ + +The directory where the symlinks to the mounts in `mounts`_ are created. + + +``users`` +~~~~~~~~~ + +The list of users/groups, who are allowed to log in. Group names must be +prefixed with ``%``. diff --git a/admin-guide/puppet/roles/daq_buffer.rst b/admin-guide/puppet/roles/daq_buffer.rst new file mode 100644 index 00000000..fd82458a --- /dev/null +++ b/admin-guide/puppet/roles/daq_buffer.rst @@ -0,0 +1,17 @@ +``role::daq_buffer`` +==================== + +A data acquisition server. This role assumes to be running on a system with two +disks, ``/dev/sda`` and ``/dev/sdb``. Apart from the usual LVs for the OS there +is another LV for metadata on ``/dev/sda`` (as usual). On ``/dev/sdb`` there is +a single LV for the actual data. + + +Parameters +---------- + +``daq_admins`` +~~~~~~~~~~~~~~ + +A list of users with full root access on the system (in addition to the usual +``aaa::admins``). diff --git a/admin-guide/puppet/roles/dcache_t3_pools.rst b/admin-guide/puppet/roles/dcache_t3_pools.rst new file mode 100644 index 00000000..53735ac8 --- /dev/null +++ b/admin-guide/puppet/roles/dcache_t3_pools.rst @@ -0,0 +1,4 @@ +``role::dcache::t3_pools`` +========================== + +This role implements a DCache pool for the Tier3. diff --git a/admin-guide/puppet/roles/desktop.rst b/admin-guide/puppet/roles/desktop.rst new file mode 100644 index 00000000..aca4eced --- /dev/null +++ b/admin-guide/puppet/roles/desktop.rst @@ -0,0 +1,28 @@ +``role::desktop`` +====================== + +This role implements a generic desktop system. The following features are +supported: + +- AFS (optional), with automatic token renewal +- AD authentication +- Printing via the PSI CUPS server +- Multiple keyboard layouts on the login screen +- Kerberos support for Firefox + + +Parameters +---------- + +``local_homes`` +~~~~~~~~~~~~~~~ + +If ``true``, then home directories are on local disk in ``/home``, otherwise the +home directory is determined by AD. + + +``priv_users`` +~~~~~~~~~~~~~~ + +A list of privileged users. Every user on this list has full root and is a +member of the wheel group.n diff --git a/admin-guide/puppet/roles/ganglia_server.rst b/admin-guide/puppet/roles/ganglia_server.rst new file mode 100644 index 00000000..9b8a38bd --- /dev/null +++ b/admin-guide/puppet/roles/ganglia_server.rst @@ -0,0 +1,5 @@ +``role::ganglia_server`` +======================== + +This role implements a server running the Ganglia web interface for a Ganglia +grid. diff --git a/admin-guide/puppet/roles/grafana.rst b/admin-guide/puppet/roles/grafana.rst new file mode 100644 index 00000000..169138a5 --- /dev/null +++ b/admin-guide/puppet/roles/grafana.rst @@ -0,0 +1,6 @@ +``role::grafana`` +================= + +This role implements a server running the Grafana web interface. + +For details on its configuration see the :doc:`grafana profile <../profiles/grafana>`. diff --git a/admin-guide/puppet/roles/hpc/ces.rst b/admin-guide/puppet/roles/hpc/ces.rst new file mode 100644 index 00000000..27f38f37 --- /dev/null +++ b/admin-guide/puppet/roles/hpc/ces.rst @@ -0,0 +1,2 @@ +``role::hpc::ces`` +================== diff --git a/admin-guide/puppet/roles/hpc/cn.rst b/admin-guide/puppet/roles/hpc/cn.rst new file mode 100644 index 00000000..6cdeec56 --- /dev/null +++ b/admin-guide/puppet/roles/hpc/cn.rst @@ -0,0 +1,20 @@ +``role::hpc::cn`` +====================== + +This role implements a Computing Node. Currently only Slurm is supported. +GPFS can be configured, but need changes in Puppet for newer clusters:: + + # Cluster specific classes + case $cluster['name'] { + 'merlin5','ComputeCluster_SwissFEL','ra','xbl','sf': { + class { 'profile::gpfs':; } + } + } + +Parameters +---------- + +``cluster`` +~~~~~~~~~~~~~~~ + +Must be defined by the setting: ``slurm::cluster`` in YAML. diff --git a/admin-guide/puppet/roles/hpc/database.rst b/admin-guide/puppet/roles/hpc/database.rst new file mode 100644 index 00000000..b244e4d7 --- /dev/null +++ b/admin-guide/puppet/roles/hpc/database.rst @@ -0,0 +1,4 @@ +``role::hpc::database`` +======================= + +This role implements a MySQL server for Slurm. diff --git a/admin-guide/puppet/roles/hpc/server.rst b/admin-guide/puppet/roles/hpc/server.rst new file mode 100644 index 00000000..360a7992 --- /dev/null +++ b/admin-guide/puppet/roles/hpc/server.rst @@ -0,0 +1,64 @@ +``role::hpc::server`` +====================== + +This role implements a Server node. Currently only Slurm is supported. +GPFS can be configured, but need changes in Puppet for newer clusters:: + + # Cluster specific classes + case $cluster['name'] { + 'merlin5': { + class { 'profile::gpfs':; } + } + } + +Parameters +---------- + +=========== ========= ========================== +**Name** **Type** **Default** +----------- --------- -------------------------- +has_slurm Boolean *true* +cluster Hash *slurm::cluster* +db_user String *slurm::db::user* +db_password String *slurm::db::password* +db_backup Boolean *slurm::db::backup* +=========== ========= ========================== + +``has_slurm`` +~~~~~~~~~~~~~~~ + +When set to ``true``, installs and configured a **slurm** server. +By default **slurm** is always installed, it can be disabled by setting this +parameter to ``false`` + +``cluster`` +~~~~~~~~~~~~~~~ + +Must be defined by the setting ``slurm::cluster`` in YAML. + +``db_user`` +~~~~~~~~~~~~~~~ + +Must be defined by the setting ``slurm::db::user`` in YAML. + +``db_passwd`` +~~~~~~~~~~~~~~~ + +Must be defined by the setting ``slurm::db::password`` in YAML. + +``db_backup`` +~~~~~~~~~~~~~~~ + +Must be defined by the setting ``slurm::db::backup`` in YAML. + +``db_options`` +~~~~~~~~~~~~~~~ + +Can be defined by the setting ``slurm::db::options`` in YAML. +Defaults to ``{}`` + +``db_backup_dir`` +~~~~~~~~~~~~~~~~~ + +Can be defined by the setting ``slurm::db::backup_dir`` in YAML. +Defaults to ``undef`` diff --git a/admin-guide/puppet/roles/hpc/ui.rst b/admin-guide/puppet/roles/hpc/ui.rst new file mode 100644 index 00000000..6152cd51 --- /dev/null +++ b/admin-guide/puppet/roles/hpc/ui.rst @@ -0,0 +1,20 @@ +``role::hpc::ui`` +====================== + +This role implements a User Interface. Currently only Slurm is supported. +GPFS can be configured, but need changes in Puppet for newer clusters:: + + # Cluster specific classes + case $cluster['name'] { + 'merlin5','xbl','sf': { + class { 'profile::gpfs':; } + } + } + +Parameters +---------- + +``cluster`` +~~~~~~~~~~~~~~~ + +Must be defined by the setting: ``slurm::cluster`` in YAML. diff --git a/admin-guide/puppet/roles/influxdb.rst b/admin-guide/puppet/roles/influxdb.rst new file mode 100644 index 00000000..fcc27fec --- /dev/null +++ b/admin-guide/puppet/roles/influxdb.rst @@ -0,0 +1,5 @@ +``role::influxdb`` +================== + +This role implements a simple InfluxDB server. It is used in combination with +the :doc:`telegraf client <../profiles/telegraf>`. diff --git a/admin-guide/puppet/roles/jupyterserver.rst b/admin-guide/puppet/roles/jupyterserver.rst new file mode 100644 index 00000000..2aa693b4 --- /dev/null +++ b/admin-guide/puppet/roles/jupyterserver.rst @@ -0,0 +1,5 @@ +``role::jupyterserver`` +========================= + +This role implements a Jupyterhub service that can spawn singleuser servers +on cluster nodes via a batch system. diff --git a/admin-guide/puppet/roles/log_server.rst b/admin-guide/puppet/roles/log_server.rst new file mode 100644 index 00000000..6f0bc3ef --- /dev/null +++ b/admin-guide/puppet/roles/log_server.rst @@ -0,0 +1,5 @@ +``role::log_server`` +========================= + +This role implements a syslog server, accepting logs via UDP and TCP on +port 514. diff --git a/admin-guide/puppet/roles/login_server.rst b/admin-guide/puppet/roles/login_server.rst new file mode 100644 index 00000000..897d34b3 --- /dev/null +++ b/admin-guide/puppet/roles/login_server.rst @@ -0,0 +1,5 @@ +``role::login_server`` +=========================== + +This role implements a login server. Its primary purpose is to allow users +without Linux workstations to work with Linux tools. diff --git a/admin-guide/puppet/roles/media_station.rst b/admin-guide/puppet/roles/media_station.rst new file mode 100644 index 00000000..58c246ae --- /dev/null +++ b/admin-guide/puppet/roles/media_station.rst @@ -0,0 +1,6 @@ +``role::media_station`` +======================= + +A media station, ie. a workstation for transferring experimental data to +external media (usually USB disks) and for managing said media. + diff --git a/admin-guide/puppet/roles/nomachine_proxy.rst b/admin-guide/puppet/roles/nomachine_proxy.rst new file mode 100644 index 00000000..5e302f6e --- /dev/null +++ b/admin-guide/puppet/roles/nomachine_proxy.rst @@ -0,0 +1,34 @@ +``role::nomachine_proxy`` +========================= + +This role implements a NoMachine proxy, acting as a HUB to access +to other machines through SSH. + + +Parameters +---------- + +================== ===================== =============================================================================== +**Name** **Type** **Default** +------------------ --------------------- ------------------------------------------------------------------------------- +$nomachine_desktop Enum['gnome','icewm'] ``hiera('nomachine::proxy::desktop_environment')`` +$banner_message String ``hiera('nomachine::gnome::banner', 'Wellcome to the NoMachine Proxy Server')`` +$keyboard_layouts Array ``hiera('nomachine::gnome::keyboards', ['us','de'])`` +================== ===================== =============================================================================== + +```nomachine_desktop``` +~~~~~~~~~~~~~~~~~~~~~~~ + +Must be defined. Please refer to ``common.yaml`` to see the default value. Currently ``gnome`` is only supported. +For ``icewm`` changes must be done in this class. + +```banner_message``` +~~~~~~~~~~~~~~~~~~~~ + +Customize Banner message. This can be done from hiera with ``nomachine::gnome::banner`` + +```keyboard_layouts``` +~~~~~~~~~~~~~~~~~~~~~~ + +Modify this in order to add or remove the default keyboard layouts. This can be done from hiera with +``nomachine::gnome::keyboards`` diff --git a/admin-guide/puppet/roles/reverse_proxy.rst b/admin-guide/puppet/roles/reverse_proxy.rst new file mode 100644 index 00000000..8d921a0f --- /dev/null +++ b/admin-guide/puppet/roles/reverse_proxy.rst @@ -0,0 +1,55 @@ +``role::reverse_proxy`` +======================= + +A reverse proxy based on Apache, which maps a set of URLs to other URLs on +various backend systems. + + +Parameters +---------- + +=========== ========= ============ +**Name** **Type** **Default** +----------- --------- ------------ +tls_cert string +tls_chain string +tls_key string +backends hash +allow_from string +=========== ========= ============ + + +``tls_cert`` +~~~~~~~~~~~~ + +The TLS certificate (PEM). + + +``tls_chain`` +~~~~~~~~~~~~~ + +The TLS certificate chain, ie. the intermediate certificate concatenated with +the host's certificate. + + +``tls_key`` +~~~~~~~~~~~ + +The TLS key (PEM). **Must be encrypted**! + + +``backends`` +~~~~~~~~~~~~ + +A hash describing the URLs to be proxied. The keys are the URLs relative to the +hostname, the values are hashes containing the following keys: + +- ``url``: the URL to forward requests to + + +``allow_from`` +~~~~~~~~~~~~~~ + +An expression controlling access to the reverse proxy. Syntax as described in +the `Apache manual +`_ diff --git a/admin-guide/puppet/roles/server.rst b/admin-guide/puppet/roles/server.rst new file mode 100644 index 00000000..c9c6b2ff --- /dev/null +++ b/admin-guide/puppet/roles/server.rst @@ -0,0 +1,5 @@ +``role::server`` +===================== + +This role implements a generic server. Only basic system functionality is +managed, e.g. authentication or logging. diff --git a/admin-guide/puppet/roles/slurm_client.rst b/admin-guide/puppet/roles/slurm_client.rst new file mode 100644 index 00000000..cfd136c7 --- /dev/null +++ b/admin-guide/puppet/roles/slurm_client.rst @@ -0,0 +1,4 @@ +``role::slurm_client`` +~~~~~~~~~~~~~~~~~~~~~~ + +**Deprecated**, please use ``role::hpc::ui`` instead. diff --git a/admin-guide/puppet/roles/slurm_compute.rst b/admin-guide/puppet/roles/slurm_compute.rst new file mode 100644 index 00000000..ae58ff33 --- /dev/null +++ b/admin-guide/puppet/roles/slurm_compute.rst @@ -0,0 +1,4 @@ +``role::slurm_compute`` +~~~~~~~~~~~~~~~~~~~~~~~ + +**Deprecated**, please use ``role::hpc::cn`` instead. diff --git a/admin-guide/puppet/roles/slurm_server.rst b/admin-guide/puppet/roles/slurm_server.rst new file mode 100644 index 00000000..355331a7 --- /dev/null +++ b/admin-guide/puppet/roles/slurm_server.rst @@ -0,0 +1,4 @@ +``role::slurm_server`` +~~~~~~~~~~~~~~~~~~~~~~ + +**Deprecated**, please use ``role::hpc::server`` instead. diff --git a/admin-guide/puppet/roles/softioc.rst b/admin-guide/puppet/roles/softioc.rst new file mode 100644 index 00000000..d7f30ae9 --- /dev/null +++ b/admin-guide/puppet/roles/softioc.rst @@ -0,0 +1,64 @@ +``role::softioc`` +================= + +This role implements a GFA SoftIOC system. + + +Parameters +---------- + +============== ======== =================================== +local_homes bool hiera('softioc::local_homes') +mount_root string hiera('softioc::mount_root') +mounts hash hiera_hash('softioc::mounts', {}) +symlink_root string hiera('softioc::symlink_root') +users array hiera('softioc::users', []) +============== ======== =================================== + + +``local_homes`` +~~~~~~~~~~~~~~~ + +If this is true, the home directories on the system will be in ``/home/%u``. + + +``mount_root`` +~~~~~~~~~~~~~~ + +The directory where the mounts given in ``mounts`` are mounted. + + +``mounts`` +~~~~~~~~~~ + +A hash defining the mounts to be mounted below ``mount_root``. + + +``symlink_root`` +~~~~~~~~~~~~~~~~ + +This defines the directory where symlinks to the mounts defined by ``mounts`` +are created. + + +``users`` +~~~~~~~~~ + +This overrides the ``aaa::users`` parameter. + + +Examples +-------- + +Configuration:: + + softioc::mount_root: '/gfa/.mounts' + softioc::symlink_root: '/sf' + softioc::mounts: + 'data': + ... + +Resulting files: + +- ``/gfa/.mounts/data``: mountpoint for ``data`` +- ``/sf/data ``: symlink to ``/gfa/.mounts/data`` diff --git a/admin-guide/puppet/roles/web_server.rst b/admin-guide/puppet/roles/web_server.rst new file mode 100644 index 00000000..0f1960e5 --- /dev/null +++ b/admin-guide/puppet/roles/web_server.rst @@ -0,0 +1,26 @@ +``role::web_server`` +==================== + +This role implements a simple web server which simply exports directories under +certain URLs. + + +Parameters +---------- + +``directories`` +~~~~~~~~~~~~~~~ + +A hash whose keys are the (relative) URLs under which to export the directories. +The values of the hash are the directories that should be made available. + + +Examples +-------- + +The following configuration exports ``/usr/share/doc`` as +``$FQDN/documentation`` and ``/usr/share/man`` as ``$FQDN/manpages``:: + + web_server::directories: + '/documentation': '/usr/share/doc' + '/manpages': '/usr/share/man' diff --git a/admin-guide/puppet/roles/workstation.rst b/admin-guide/puppet/roles/workstation.rst new file mode 100644 index 00000000..24b7977d --- /dev/null +++ b/admin-guide/puppet/roles/workstation.rst @@ -0,0 +1,103 @@ +``role::workstation`` +===================== + +This role implements a generic desktop system. The following features are +supported: + +- AFS (optional), with automatic token renewal +- AD authentication +- Printing via the PSI CUPS server +- Multiple keyboard layouts on the login screen +- Kerberos support for Firefox + + +Parameters +---------- + + +================= ========= ======================================== +**Name** **Type** **Default** +----------------- --------- ---------------------------------------- +banner_message string See ``common.yaml`` +favorites array See ``common.yaml`` +keyboard_layouts array See ``common.yaml`` +local_homes bool false +priv_users array [] +idle_delay integer hiera('workstation::idle_delay') +lock_delay integer hiera('workstation::lock_delay') +lock_enabled boolean hiera('workstation::lock_enabled') +timedlogin_delay integer hiera('workstation::timedlogin_delay') +timedlogin_enable boolean hiera('workstation::timedlogin_enable') +timedlogin_user string hiera('workstation::timedlogin_user') +================= ========= ======================================== + +``banner_message`` +~~~~~~~~~~~~~~~~~~ + +A message displayed on the login screen. + + +``favorites`` +~~~~~~~~~~~~~ + +The of applications/locations in the 'Favorites' menu. Entries usually specify +an application's desktop file, eg. 'firefox.desktop'. + + +``idle_delay`` +~~~~~~~~~~~~~~ + +The number of seconds before the screensaver is started. Also see `lock_delay`_ +and `lock_enabled`_. + + +``keyboard_layouts`` +~~~~~~~~~~~~~~~~~~~~ + +The list of keyboard layouts available on the login screen. + + +``local_homes`` +~~~~~~~~~~~~~~~ + +Whether or not to use local homes in ``/home``. + + +``lock_delay`` +~~~~~~~~~~~~~~ + +The number of seconds to wait after the start of the screensaver before locking +the screen. Also see `idle_delay`_. + + +``lock_enabled`` +~~~~~~~~~~~~~~~~ + +Whether or not to lock the screen after a period of inactivity. See +`idle_delay`_ and `lock_delay`_ for more. + + +``priv_users`` +~~~~~~~~~~~~~~ + +A list of users, which will have admin privileges in the UI. They can install +additional software, for example. + + +``timedlogin_delay`` +~~~~~~~~~~~~~~~~~~~~ + +How many seconds to wait at the login screen before logging in automatically. + + +``timedlogin_enable`` +~~~~~~~~~~~~~~~~~~~~~ + +Enable automatic logins. This does not work with accounts which require AFS, of +course. + + +``timedlogin_user`` +~~~~~~~~~~~~~~~~~~~ + +Which user to log in as if automatic logins have been enabled. diff --git a/admin-guide/puppet/roles/zookeeper.rst b/admin-guide/puppet/roles/zookeeper.rst new file mode 100644 index 00000000..af7e92cc --- /dev/null +++ b/admin-guide/puppet/roles/zookeeper.rst @@ -0,0 +1,30 @@ +``role::zookeeper`` +=================== + +This role implements a `zookeeper `_ server. It +only writes the configuration files and enables and starts the service. It *does +not* install the necessary packages. + + +Parameters +---------- + +Technically this role has no parameters, but the following parameters are used +by ``profile::zookeeper``. + +================= ========= ========================================= +myid string hiera('zookeeper::myid') +zookeeper_nodes array hiera('zookeeper::zookeeper_nodes', []) +================= ========= ========================================= + + +``myid`` +~~~~~~~~ + +The unique ID of the zookeeper node. + + +``zookeeper_nodes`` +~~~~~~~~~~~~~~~~~~~ + +The list off zookeeper nodes in the cluster. diff --git a/admin-guide/selinux.rst b/admin-guide/selinux.rst new file mode 100644 index 00000000..60ef75e1 --- /dev/null +++ b/admin-guide/selinux.rst @@ -0,0 +1,150 @@ +SELinux +======= + +Depending on the Puppet role and Hiera settings, SELinux can be enabled by +default. This is recommended especially for systems which are accessible from +outside PSI. + +This section provides basic information on SELinux in general, common problems +and how to solve them. + + +SELinux +------- + +Information on SELinux can be found here: + +- `Mandatory Access Control `_ +- :download:`SELinux coloring book + ` (`original + `_) + + +SELinux modes +------------- + +SELinux can be in one of three modes: + +- ``enforcing`` + + The SELinux policy is enforced, violations are logged. + +- ``permissive`` + + The SELinux policy is **not** enforced, but violations are still logged. + +- ``disabled`` + + SELinux is not loaded at all. + + +Going from ``enforcing`` or ``permissive`` to/from ``disabled`` requires a +reboot. + + +SELinux contexts +---------------- + +On an SELinux system every file has a context, and the SELinux policy controls +whether a confined service can access files of a given context. + +The context of files can be listed with the :manpage:`stat(1)` command or by passing +the ``-Z`` option to ``ls(1)``:: + + $ ls -Z /etc/fstab + -rw-r--r--. root root system_u:object_r:etc_t:s0 /etc/fstab + + $ stat /etc/fstab + File: ‘/etc/fstab’ + Size: 619 Blocks: 8 IO Block: 4096 regular file + Device: fd01h/64769d Inode: 134320258 Links: 1 + Access: (0644/-rw-r--r--) Uid: ( 0/ root) Gid: ( 0/ root) + Context: system_u:object_r:etc_t:s0 + Access: 2017-05-13 21:50:43.533927373 +0200 + Modify: 2016-04-03 04:19:02.289004083 +0200 + Change: 2016-04-03 04:29:29.955011505 +0200 + Birth: - + + + +When files are created they are assigned a default context based on their path +according to the system policy. + +The default contexts configured for various filesystem locations can be listed +by running :manpage:`semanage(8)`:: + + $ semanage fcontext -l + ... + /usr/.* all files system_u:object_r:usr_t:s0 + /var/.* all files system_u:object_r:var_t:s0 + /run/.* all files system_u:object_r:var_run_t:s0 + /srv/.* all files system_u:object_r:var_t:s0 + ... + + +It is possible to add/list local customizations to the default contexts of the +system:: + + + $ semanage fcontext -a -t httpd_sys_content_t '/srv/web/data(/.*)?' + $ semanage fcontext -a -t etc_t /srv/web/httpd.conf + + $ semanage fcontext -l -C + /srv/web/httpd.conf all files system_u:object_r:etc_t:s0 + /srv/web/data(/.*)? all files system_u:object_r:httpd_sys_content_t:s0 + + +Use the :manpage:`restorecon(8)` command to restore the context of a file or +directory tree according to the system policy:: + + $ restorecon -v /etc/fstab + $ restorecon -vR /etc/puppetlabs/ + + +It is also possible to trigger a relabeling of all files with default contexts +by:: + + touch /.autorelabel + reboot + + +For debugging or during development the :manpage:`chcon(1)` command can be used:: + + chcon -t etc_t /srv/web/httpd.conf + +.. important:: This is not enough! The next ``restorecon(8)``, relabeling, or system + redeployment will not honor the changes made with :manpage:`chcon(1)`. Use + :manpage:`semanage(8)` as described above or change the location of the files + in question so that they are classified correctly by the system policy. + + +SELinux Booleans +---------------- + +SELinux booleans are variables which control certain restrictions enforced by +the SELinux policy. An example would be ``httpd_can_network_connect``, which +controls whether Apache can open network connections. + +The state of SELinux booleans is either ``on`` or ``off`` and can be queried +using :manpage:`getsebool(8)`:: + + # List all SELinux booleans and their states + getsebool -a + + # Show the state of a given variable + getsebool httpd_can_network_connect + + +The :manpage:`setsebool(8)` command changes the state of a boolean:: + + setsebool httpd_can_network_connect on + + +Puppet development +------------------ + +All Puppet modules should support SELinux. Modules which do, eg. +``profile::aaa``, must be tested with SELinux systems in enforcing mode. + +SELinux configuration is done through ``role::base`` and the ``selinux`` +component. diff --git a/admin-guide/software.rst b/admin-guide/software.rst new file mode 100644 index 00000000..6192382f --- /dev/null +++ b/admin-guide/software.rst @@ -0,0 +1,94 @@ +Software and Licenses +===================== + + +.. toctree:: + :maxdepth: 1 + + software/updates + + +Licenses +======== + +Our Red Hat Enterprise Linux subscriptions are provided by ETHZ, other licenses +are usually managed by Roland Blättler. + +The RHEL repositories can be accessed on the `ETHZ Satellite server +`_. It is only accessible from within PSI and a +special account is needed, which can be requested at +https://cd-portal.sp.ethz.ch/_layouts/15/start.aspx#/SitePages/Home.aspx. + +One thing to keep in mind is that several groups at PSI use the Satellite server +directly, so not all PSI hosts known to the Satellite belong to the central +Linux environment. In particular the network team has a number of systems there. + +Normally only certain infrastructure systems are registered with the Satellite, +at this point the Puppet server (``puppet00.psi.ch``), the repository server +(``repo00.psi.ch``), and the boot server (``boot00.psi.ch``). + +About once a year we report the total number of systems to ETHZ, so they can +track subscription usage. When we started using the ETHZ subscriptions in 2016 +we provided an estimate of 2000 systems max. + + +Distribution and deployment +--------------------------- + +All software is distributed as RPMs with the following exceptions: + +- some software is provided via AFS/NFS instead +- configuration files and scripts that can be considered configuration, e.g. the + files in ``/etc/cron.daily`` +- server applications can be deployed by cloning a Git repository (e.g. sysdb) + +There are a number of advantages to deploying software as RPM: + +- automatic installation/protection of dependencies +- inventory of installed software (``rpm -qa`` etc) including version + information +- integrity checking (``rpm -q --verify``) +- ownership tracking (``rpm -qf``, ``yum provides``) +- no network dependency, which is useful for laptops and increases reliability + on other systems + + +Repositories +------------ + +We maintain an internal mirror for every repository that we use, or at least a +local repository containing the specific packages. We never point ``yum.conf`` +(or any other package manager) to an external repository directly. + +The repository server is ``repo00.psi.ch``, and there is a corresponding test +system, ``repo00-test.psi.ch``. + +Currently we maintain the following repositories: + +1. RHEL 7 (almost all channels) +2. EPEL for RHEL 7 +3. Puppetlabs PC1 +4. Google Chrome +5. OpenAFS (PSI) +6. GPFS (PSI) +7. OpenHPC + +The mirroring is done using :manpage:`reposync(1)` with custom :manpage:`yum.conf` files. + + +The script to run a sync of all the repositories is `/opt/pli/sbin/psi-mirror-yum` but is +currently not executed automatically. + +To add a new repository to the list the files `/opt/pli/etc/mirror/yum.conf` and +`/opt/pli/etc/mirror/repolist` should be edited. The first file contains the repositories +definitions, the second one the list of repositories to mirror. + + + +Packaging +--------- + +All packaging information for in-house packages must be tracked in Git. The +repositories containing packaging information should be in the +`linux-packages `_ group on the +Gitlab server. diff --git a/admin-guide/software/updates.rst b/admin-guide/software/updates.rst new file mode 100644 index 00000000..3be1a5fc --- /dev/null +++ b/admin-guide/software/updates.rst @@ -0,0 +1,70 @@ +Updates +======= + +There are two major aspects to software updates on PSI Linux systems: + +1. The configured repositories. +2. The Update policy + +Generally the assumption is that ``/etc/yum.conf`` points the system at +repositories which, for each package, contain the version of that package which +should be installed on the system, and possibly older versions. This way, a +simple ``yum update`` would always bring a system to the desired state, even +though it is not recommended to actually run ``yum update`` directly (see +below). + +The policy answers the following questions: + +1. When should updates be installed? +2. Which types of updates should be installed? I.e. security fixes, security and + bug fixes, or all updates? +3. When should the system reboot? I.e. always (offline updates, recommended), + only when there is a new kernel, or never? +4. For how long can updates be pending before an alert is triggered? + + +Policy +------ + +Parameters: +- timing (never, timespec) +- severity +- reboot behaviour (always, only if necessary (kernel update or needs-restarting), never) + +Example of fully automatic updates with mandatory reboots:: + + update::schedule: Thu, 02:00 -- 04:00 + update::severity: 'security' + update::reboot: 'always' + + +Example of manually triggered, full updates with reboots if necessary:: + + update::schedule: 'never' + update::severity: 'all' + update::reboot: 'if-necessary' + + + +Procedure +--------- + +Updates should be performed by starting the ``psi-update`` service. Using this +service instead of running ``yum`` directly has a number of benefits: + +1. All update-related log output can be retrieved from the journal easily using + ``journalctl -u psi-update.service``. +2. The service will take into account the update policy even when in manual + mode, e.g. it will only install the desired types of updates. +3. The service will automatically notify monitoring systems if a reboot is + necessary, avoiding false positives. +4. It will take of any cleanup actions necessary. E.g. Splunk, a commercial + logging product requires to accept its license again after updates (by + running something like ``splunk --accept-license``). + + +Monitoring +---------- + +There will be a separate mechanism, e.g. a Nagios check, to alert on systems +that are not compliant with their update policy. diff --git a/admin-guide/third-party.rst b/admin-guide/third-party.rst new file mode 100644 index 00000000..35e21c47 --- /dev/null +++ b/admin-guide/third-party.rst @@ -0,0 +1,22 @@ +Third-party Documentation +========================= + +.. _bash_style_guides: + + +Style Guides/Coding standards +----------------------------- + +.. To add a new version to this repository, save as HTML in Firefox and copy to /_static. + +1. The :download:`Google Shell Style Guide ` + (`original `_) + + +Product Documentation +--------------------- + +1. `Red Hat Enterprise Linux documentation `_: + + - `Desktop Migration and Administration Guide `_ + diff --git a/admin-guide/troubleshooting.rst b/admin-guide/troubleshooting.rst new file mode 100644 index 00000000..f508a221 --- /dev/null +++ b/admin-guide/troubleshooting.rst @@ -0,0 +1,9 @@ +Troubleshooting +=============== + +.. toctree:: + :maxdepth: 2 + + troubleshooting/methods-and-tools + troubleshooting/deployment + troubleshooting/login diff --git a/admin-guide/troubleshooting/deployment.rst b/admin-guide/troubleshooting/deployment.rst new file mode 100644 index 00000000..79f03f31 --- /dev/null +++ b/admin-guide/troubleshooting/deployment.rst @@ -0,0 +1,91 @@ +============ + Deployment +============ + +Deployment roughly has the following phases: + +1. DHCP followed by PXE boot. +2. Kickstart installation followed by a reboot. +3. Initial Puppet run, followed by updates, followed by another Puppet run and a + reboot. + + +PXE boot/iPXE +============= + +When deployment fails during the PXE phase it usually due to one of the +following: + +1. No network connectivity + + This is usually indicated by messages similar to ``No link on XXX``. + +2. No DHCP in the connected network (eg DMZ, tier3) + + The DHCP requests by the BIOS/UEFI firmware will time out. + +3. Firewall (no TFTP/HTTP to the relevant servers) +4. Incompatibilities between iPXE and network card (NIC) +5. Incorrect sysdb entry (hence iPXE entry incorrect). + +If there is not DHCP, the static network information provided manually is +possibly wrong or for a different network than the one connected to the host. + + +Infiniband +---------- + +Infiniband can generally cause installation problem, expecially in the +initial phase, when iPXE tries to load the configuration file. + +As a general rule, disable PXE on all Infiniband cards. + +Anyway this is not always enough since it happens that iPXE recognized +anyway the Infiniband card as the first device (with MAC +address ``79:79:79:79:79:79``) and tries to get configuration file for +that. + + +Kickstart +========= + +Typical problems during the Kickstart phase: + +1. The Kickstart file cannot be retrieved from the boot server + ``boot00.psi.ch``. Typically caused by incorrect sysdb entries or firewalls. +2. Partitioning fails. This can happen because + + a) No disk is recognized, or the wrong disk is used + b) Packages or other installation data cannot be downloaded. Can be caused by + firewalls or incorrect sysdb entries. + + +First Puppet Run +================ + +A typical problem are Hiera errors, eg the following:: + + # puppet agent --test + Info: Using configured environment 'prod' + Info: Retrieving pluginfacts + Info: Retrieving plugin + Info: Loading facts + Error: Could not retrieve catalog from remote server: Error 500 on SERVER: Server Error: Evaluation Error: Error while evaluating a Resource Statement, Function lookup() did not find a value for the name 'console::mount_root' at /srv/puppet/code/dev/envs/prod/code/modules/role/manifests/console.pp:1 on node lxdev05.psi.ch + Warning: Not using cache on failed catalog + Error: Could not retrieve catalog; skipping run + +The error message shows that the value for ``console::mount_root`` could not be +found in Hiera. + +Sometimes the Active Directory join fails, usually for one of these three +reasons: + +- There is already an Active Directory computer object for the same system from + a previous Windows installation. In this case, delete the computer object and + restart the installation. +- Firewall restrictions +- Old Puppet certificates from a previous SL6 installation are used on the + system. In this case delete the certificates on the client with ``find + /etc/puppetlabs -name '*.pem' -delete`` and clean up any certificates on the + Puppet server with ``puppet cert clean $HOSTNAME``. Then restart the + installation. diff --git a/admin-guide/troubleshooting/login.rst b/admin-guide/troubleshooting/login.rst new file mode 100644 index 00000000..3b369661 --- /dev/null +++ b/admin-guide/troubleshooting/login.rst @@ -0,0 +1,28 @@ +========================= + Login and Remote Access +========================= + +When a user cannot log in on a system, it is usually caused by one of these: + +1. The password is wrong. +2. Access hasn't been granted through Hiera (``aaa::admins`` and ``aaa::users``) + or ``/etc/security/ssh.allow.*``. The latter also has to be enabled in Hiera. +3. Log in as root is attempted from a system that is not a bastion host (eg + ``wmgt0*.psi.ch`` or ``*-gw.psi.ch``). +4. In the case of Gnome logins, the problem might be caused by the home + directory being inaccessible (eg because AFS doesn't work properly). +5. :manpage:`sssd(8)` may have problems. + +Regarding #3 note that on some systems the configured bastion host is +``wmgt*.psi.ch`` even though it is not actually possible to log in from there, +because the PSI firewall only allows connections from a certain gateway, eg +``foobar-gw.psi.ch``. + + +Notes +===== + +For normal users there will be a :manpage:`pam_access(8)` error even for +successful logins. The reason is that we use pam_access twice. First for admins +and then - depending on the system's configuration - for normal users. Obviously +the first one will fail unless the user in question is recognized as an admin. diff --git a/admin-guide/troubleshooting/methods-and-tools.rst b/admin-guide/troubleshooting/methods-and-tools.rst new file mode 100644 index 00000000..3b694e8f --- /dev/null +++ b/admin-guide/troubleshooting/methods-and-tools.rst @@ -0,0 +1,269 @@ +=================== + Methods and Tools +=================== + +This section covers the general methods and tools available for troubleshooting +RHEL Linux systems. + +Methodology +=========== + +When solving problems it is helpful to use a structured approach (as opposed to +randomly trying things until the system seems to work again) and to keep notes. + +The `Google SRE book `_ has useful +information, especially the `chapter on troubleshooting +`_ + + +Tools +===== + + +Services +-------- + +Services can be inspected with :manpage:`systemctl(1)`. Example:: + + ● sssd.service - System Security Services Daemon + Loaded: loaded (/usr/lib/systemd/system/sssd.service; enabled; vendor preset: disabled) + Active: active (running) since Thu 2018-06-21 16:26:48 CEST; 5 days ago + Main PID: 691 (sssd) + CGroup: /system.slice/sssd.service + ├─691 /usr/sbin/sssd -i --logger=files + ├─746 /usr/libexec/sssd/sssd_be --domain D.PSI.CH --uid 0 --gid 0 --logger=files + ├─758 /usr/libexec/sssd/sssd_nss --uid 0 --gid 0 --logger=files + └─759 /usr/libexec/sssd/sssd_pam --uid 0 --gid 0 --logger=files + + Jun 21 16:26:48 lxdev05.psi.ch systemd[1]: Starting System Security Services Daemon... + Jun 21 16:26:48 lxdev05.psi.ch sssd[691]: Starting up + Jun 21 16:26:48 lxdev05.psi.ch sssd[be[D.PSI.CH]][746]: Starting up + Jun 21 16:26:48 lxdev05.psi.ch sssd[pam][759]: Starting up + Jun 21 16:26:48 lxdev05.psi.ch sssd[nss][758]: Starting up + Jun 21 16:26:48 lxdev05.psi.ch systemd[1]: Started System Security Services Daemon. + Jun 25 10:59:22 lxdev05.psi.ch [sssd[krb5_child[5223]]][5223]: Preauthentication failed + Jun 25 10:59:24 lxdev05.psi.ch [sssd[krb5_child[5224]]][5224]: Preauthentication failed + Jun 25 10:59:24 lxdev05.psi.ch [sssd[krb5_child[5224]]][5224]: Preauthentication failed + + +Processes +--------- + +Processes can be investigated through a variety of tools: + +1. The files in ``/proc/$PID/``, in particular + + a) ``/proc/$PID/fd/*``: the open files of the process + b) ``/proc/$PID/environ``: the process' environment + +2. :manpage:`strace(1)` allows tracing a process' system calls. +3. :manpage:`ltrace(1)` allows tracing a process' library calls. + +.. note:: Both :manpage:`strace(1)` and :manpage:`ltrace(1)` slow the target + process down **a lot**, which might cause problems. + + +System and Application Logs +--------------------------- + +Starting with RHEL 7 almost all system logs end up in the journal, which can be +queried with ``journalctl``. One important exception is :manpage:`sssd(8)`, +which provides authentication against Active Directory. Its logs can be found in +``/var/log/sssd``. + + +:manpage:`journalctl` offers a lot of functionality. The following list shows +the most important features: + +1. List all reboots/show logs starting at a specific reboot:: + + # journalctl --list-boots + -10 19d173f56d314912820486b9ddfd7d6c Thu 2018-06-21 11:20:55 CEST—Thu 2018-06-21 + -9 3a5a050289314221a3863b88a0eef367 Thu 2018-06-21 11:26:33 CEST—Thu 2018-06-21 + -8 f9726e6c9ce44678ab68a2fc12b1c12c Thu 2018-06-21 11:43:38 CEST—Thu 2018-06-21 + -7 b4e6bc84ff8840adbc698992cd1900d2 Thu 2018-06-21 14:55:42 CEST—Thu 2018-06-21 + -6 81b78d0d09934937a24a73bfcd3d8ede Thu 2018-06-21 15:06:18 CEST—Thu 2018-06-21 + -5 dd78e29c073448ad9731c6c18288c97a Thu 2018-06-21 15:23:15 CEST—Thu 2018-06-21 + -4 0fc2f05d12664d3aba6364102401d5fb Thu 2018-06-21 15:29:36 CEST—Thu 2018-06-21 + -3 412bbe36d12546bab749a2a63fad99ca Thu 2018-06-21 15:34:19 CEST—Thu 2018-06-21 + -2 c5189f2006c245d7833bb8fe20e62545 Thu 2018-06-21 16:07:51 CEST—Thu 2018-06-21 + -1 7c47950edd194ff4b6a67d3556672430 Thu 2018-06-21 16:11:28 CEST—Thu 2018-06-21 + 0 61ea098edc924030aafb7a822c2df0e3 Thu 2018-06-21 16:26:46 CEST—Wed 2018-06-27 + + # journalctl -b + -- Logs begin at Thu 2018-06-21 11:20:55 CEST, end at Wed 2018-06-27 14:20:01 CEST. -- + Jun 21 16:26:46 lxdev05.psi.ch systemd-journal[85]: Runtime journal is using 8.0M (max allowed 91.9M, trying to leave 137.9M free of 911.8M av + Jun 21 16:26:46 lxdev05.psi.ch kernel: Initializing cgroup subsys cpuset + + # journalctl -b -2 + -- Logs begin at Thu 2018-06-21 11:20:55 CEST, end at Wed 2018-06-27 14:20:01 CEST. -- + Jun 21 16:07:51 lxdev05.psi.ch systemd-journal[87]: Runtime journal is using 8.0M (max allowed 91.9M, trying to leave 137.9M free of 911.8M av + Jun 21 16:07:51 lxdev05.psi.ch kernel: Initializing cgroup subsys cpuset + +2. Show logs starting from a given date/time:: + + # journalctl --since 2018-06-23 + # journalctl --since '2018-06-23 18:13' + +3. Show logs for a given unit, eg a given service:: + + # journalctl -u sshd.service + # journalctl -u pli-puppet-run.timer + +4. Show the last N messages (1000 by default):: + + # journalctl -e + # journalctl -e -n 250 + +5. List all systemd timers:: + + # journalctl list-timers + NEXT LEFT LAST PASSED UNIT ACTIVATES + Wed 2018-06-27 16:45:01 CEST 2h 16min left Tue 2018-06-26 16:45:01 CEST 21h ago systemd-tmpfiles-clean.timer systemd-tmpfiles-clean.service + Thu 2018-06-28 07:31:00 CEST 17h left Wed 2018-06-27 07:31:25 CEST 6h ago pli-puppet-run.timer pli-puppet-run.service + + 2 timers listed. + Pass --all to see loaded but inactive timers, too. + + +Filesystems and Storage +----------------------- + +Check filesystem capacity using :manpage:`df(1)`:: + + # df -h + Filesystem Size Used Avail Use% Mounted on + /dev/mapper/vg_root-lv_root 8.0G 1.4G 6.7G 17% / + devtmpfs 909M 0 909M 0% /dev + tmpfs 920M 0 920M 0% /dev/shm + tmpfs 920M 816K 920M 1% /run + tmpfs 920M 0 920M 0% /sys/fs/cgroup + /dev/sda1 976M 198M 728M 22% /boot + /dev/mapper/vg_root-lv_tmp 1014M 34M 981M 4% /tmp + /dev/mapper/vg_root-lv_var 2.9G 1.4G 1.5G 47% /var + /dev/mapper/vg_root-lv_var_log 2.0G 160M 1.9G 8% /var/log + /dev/mapper/vg_root-lv_openafs 1008M 1.3M 956M 1% /var/cache/openafs + tmpfs 184M 4.0K 184M 1% /run/user/0 + + +Check available inodes (~ the maximum number of files that can be created):: + + # df -i + Filesystem Inodes IUsed IFree IUse% Mounted on + /dev/mapper/vg_root-lv_root 4194304 48891 4145413 2% / + devtmpfs 232630 383 232247 1% /dev + tmpfs 235485 1 235484 1% /dev/shm + tmpfs 235485 575 234910 1% /run + tmpfs 235485 16 235469 1% /sys/fs/cgroup + /dev/sda1 65536 348 65188 1% /boot + /dev/mapper/vg_root-lv_tmp 524288 316 523972 1% /tmp + /dev/mapper/vg_root-lv_var 1474560 1042691 431869 71% /var + /dev/mapper/vg_root-lv_var_log 1048576 81 1048495 1% /var/log + /dev/mapper/vg_root-lv_openafs 65536 11 65525 1% /var/cache/openafs + tmpfs 235485 2 235483 1% /run/user/0 + + +Networking +---------- + +Test hostname resolution with :manpage:`getent(1)`, for example ``getent hosts +www.psi.ch``. Unlike :manpage:`nslookup(1)` or :manpage:`dig(1)`, it uses the +system resolver. + +The systems IP addresses and routes can be displayed using :manpage:`ip(8)`:: + + # ip address + 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever + 2: ens160: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 + link/ether 00:50:56:9d:6d:03 brd ff:ff:ff:ff:ff:ff + inet 10.129.160.195/24 brd 10.129.160.255 scope global ens160 + valid_lft forever preferred_lft forever + inet6 fe80::250:56ff:fe9d:6d03/64 scope link + valid_lft forever preferred_lft forever + + # ip route + default via 10.129.160.1 dev ens160 + 10.129.160.0/24 dev ens160 proto kernel scope link src 10.129.160.195 + 169.254.0.0/16 dev ens160 scope link metric 1002 + +The link status and other information of an interface can be displayed using +:manpage:`ethtool(8)`: + +1. Link status:: + + # ethtool ens160 + Settings for ens160: + [...] + Speed: 10000Mb/s + Duplex: Full + [...] + Link detected: yes + +2. Statistics (driver-specific, but look for errors/discards/dropped):: + + # ethtool -S ens160 + NIC statistics: + Tx Queue#: 0 + TSO pkts tx: 21529 + TSO bytes tx: 91036062 + ucast pkts tx: 1036632 + ucast bytes tx: 235421707 + mcast pkts tx: 8 + mcast bytes tx: 648 + bcast pkts tx: 7 + bcast bytes tx: 294 + pkts tx err: 0 + pkts tx discard: 0 + drv dropped tx total: 0 + too many frags: 0 + giant hdr: 0 + hdr err: 0 + tso: 0 + ring full: 0 + pkts linearized: 0 + hdr cloned: 0 + giant hdr: 0 + Rx Queue#: 0 + LRO pkts rx: 6913 + LRO byte rx: 100534073 + ucast pkts rx: 551554 + ucast bytes rx: 161369441 + mcast pkts rx: 4 + mcast bytes rx: 344 + bcast pkts rx: 753276 + bcast bytes rx: 45787629 + pkts rx OOB: 0 + pkts rx err: 0 + drv dropped rx total: 0 + err: 0 + fcs: 0 + rx buf alloc fail: 0 + tx timeout count: 0 + + +Packages +-------- + +The integratity of installed package can be checked with :manpage:`rpm(8)`:: + + # rpm -Vv pciutils + ......... /usr/sbin/lspci + ......... /usr/sbin/setpci + ......... /usr/sbin/update-pciids + ......... /usr/share/doc/pciutils-3.5.1 + ......... d /usr/share/doc/pciutils-3.5.1/COPYING + ......... d /usr/share/doc/pciutils-3.5.1/ChangeLog + ......... d /usr/share/doc/pciutils-3.5.1/README + ......... d /usr/share/doc/pciutils-3.5.1/pciutils.lsm + ......... d /usr/share/man/man8/lspci.8.gz + ......... d /usr/share/man/man8/setpci.8.gz + ......... d /usr/share/man/man8/update-pciids.8.gz + +Running ``rpm -Vav`` will verify **all** installed packages and take a long +time. See the man page for details on the output format. Changes, especially in +configuration files, can be normal, though.