Help-FAQ.txt

CLIP for RHEL 6 Frequently Asked Questions

0. I deployed my system and everything is broken.  HELP!
   That isn't a question but OK.  

   First, CLIP is very, very locked down.  This does not indicate breakage, 
   rather a conscious decision to address security requirements first and 
   foremost.  CLIP is not a general-purpose OS.  It is an base platform and 
   build environment that provides a starting point for developing 
   solutions that meet strict security requirements.  Red Hat Enterprise 
   Linux is a general-purpose OS (and rightly so).  The security requirements 
   of a general-purpose OS, such as using a "targeted" SELinux policy, do not 
   mesh with the requirements that must be met by security solutions.

   Second, we applied a least privilege model during development.  This means
   that we exercised the core system functions and permitted access only when
   absolutely necessary.  If you're doing something that isn't part of what
   the CLIP team considers "core system" then that access isn't accounted for
   in policy or remediation content.  

   For example, we do not consider Apache to be part of the "core system."
   Getting Apache up and running in CLIP will take a little bit of work.  
   Another example is USB support.  The remediation content disables 
   USB support.  This is aligned with the requirements and CLIP itself.
   If you need USB support you're going to have to update the remediation
   content.

   A benefit to this model is that the developer is made aware of any
   deviations from the requirements when it occurs, not during a certification
   and accreditation process.

1. How do I roll an installation ISO?
   Run "make clip-minimal-inst-iso"

2. What other things can I make?
   Run "make help"

3a. What is the default username and password for CLIP?
    The username is "toor" and the password is "neutronbass".  You can 
    change this in the %post of the kickstart
    (./kickstarts/clip-minimal/clip-minimal.ks).

3b. What is the default bootloader password for GRUB?
    The default password for GRUB is "neutronbass".  You can change this in 
    the kickstart (./kickstarts/ciip-rhel6/clip-minimal.ks).

4a. How do I set up local yum repos?
    Setup a machine that has all the appropriate yum repos in /etc/yum/repos.d.
    Ensure the yum-utils package is installed.  If it is a RHEL machine you must
    visit RHN and ensure the system is associated with the channel you wish to 
    clone.  

    RHEL can be installed without subscribing the system to RHN channels.
    To subscribe a system after installation you can use the rhn-channel command.
    E.g., to subscribe a system to the Optional channel you can use this command:
    /usr/bin/sudo rhn-channel --add --channel=rhel-x86_64-server-optional-`/bin/awk '{ print $7; }' /etc/redhat-release`.z

    Now run these commands changing the paths and repoids as appropriate to
    synchronize the yum repositories locally.

    # reposync --norepopath -m -p /opt/rhel-6-3-x86_64/rhel-x86_64-server-6 --repoid=rhel-x86_64-server-6.3.z -l
    # reposync --norepopath -m -p /opt/rhel-6-3-x86_64/rhel-x86_64-server-optional-6 --repoid=rhel-x86_64-server-optional-6.3.z -l

4b. What if I don't have access to a yum repo, but have a RHEL iso?
    You can mount the iso and copy the packages by hand to the appropriate
    directory. 

    # mkdir /mnt/rhel-iso
    # mount -o loop <path-to-RHEL-iso> /mnt/rhel-iso
    # cp /mnt/rhel-iso/Packages/* /opt/rhel-6-3-x86_64/rhel-x86_64-server6/getPackage/

    In order for the install to properly work, some RHEL optional 
    packages are required by the build system. If you do not have access to RHN
    then you will need to aquire the following RPMs and copy them to
    the local optional RHEL repo.
   
    List of RPMs:
    openscap-content-0.8.0-2.el6.x86_64.rpm
    libxslt-python-1.1.26-2.el6_3.1.x86_64.rpm
    hunspell-en-0.20090216-7.1.el6.noarch.rpm

    # cp <location-of-opt-rpms>/* /opt/rhel-6-3-x86_64/rhel-x86_64-server-optional-6/getPackage/

4c. How do I create the local yum repos?
    You can then create the repos:
    # createrepo -d /opt/rhel-6-3-x86_64/rhel-x86_64-server-6/getPackage
    # createrepo -d /opt/rhel-6-3-x86_64/rhel-x86_64-server-optional-6/getPackage

4d. How do I mirror EPEL?
    To mirror EPEL you will need to ensure the system performing the mirroring
    is already capable of pulling from EPEL. Refer to this page for help with
    that:
        http://fedoraproject.org/wiki/EPEL/FAQ#How_can_I_install_the_packages_from_the_EPEL_software_repository.3F
    Once that is complete you can mirror EPEL.  This is how we do it:

    # reposync --norepopath -m -p /opt/epel-6/ --repoid=epel  -l
    # createrepo -d /opt/epel-6/

4e. I want to use CentOS instead of RHEL. What do I need to do?
    CLIP officially supports RHEL.  That is what we test against. CentOS 
    may work but there are known issues.  For example, you will get 
    misleading results from interpreting SCAP content with SecState
    since the SCAP content uses a <platform> tag to bind the checks
    to RHEL-only.

    If you are using CentOS here is what I recommend:

    1. Mount a CentOS ISO. 
    2. Copy the contents of Packages/* to a location you put in CONFIG_REPOS.
    3. Repeat steps 1 & 2 for each ISO image (eg 2 for the DVD images).
    4. Change into the directory you copied the packages to.
    5. Run "createrepo -d ."
    6. You are ready to roll your installable image.

    Note: CentOS archives previous releases.  Currently Tresys is testing against
    RHEL 6.2 (this may have changed though).  To get a specific archived ISO from
    the CentOS mirrors use their "vault" sub-domain.  Eg:
    - http://vault.centos.org/6.2/isos/x86_64/

    
4f. Do I have to subscribe to the RHEL optional channel? 
    If you don't have credentials or you're out of entitlements there is a work-around.
    We *NEED* packages from Opt to be installed on the build host *and* need to pull
    packages from there to put on the generated installable media.  If you're using
    RHEL want to work-around this issue (hack):
        1. Grab a CentOS ISO.
        2. Mount it.
        3. Add it as a yum repo:
            http://docs.oracle.com/cd/E37670_01/E37355/html/ol_create_repo.html
        4. Re-run this script and pick CentOS.
        5. Refer to the same path in the CONFIG_REPOS file.

5. An EXCEPTION was thrown during the build.  What do I do?
   The likely culprit is an RPM that failed to roll properly. Open 
   ./repos/clip-repo/build.log.  A good option for debugging the issue
   is to roll the RPM outside of mock.  Go into packages/<PACKAGENAME>
   and run "make rpm".  It should fail to build again.  This time go into
   ./tmp/src/redhat/BUILD/<PACKAGENAME>-<PACKAGEVERSION>.  This is where the 
   build occurred.  You can now poke around in this directory to see what 
   went wrong.


6. Why do I get prompted for so many passwords the first time I login?
   The default user's password is immediately expired when the account is 
   created.  This means you have to login and choose a new password.

7a. How do I add a user?
   Use these commands (change <USERNAME> to the appropriate username): 
     # semanage user -a -R staff_r -R sysadm_r <USERNAME>_u
     # useradd -Z <USERNAME>_u -m <USERNAME>
     # restorecon -RF /home/<USERNAME>
     # passwd foo
     # chage -d 0 <USERNAME>
   Note: The first command will have to be adjusted as appropriate to match the 
         defined SELinux roles. The restorecon is required due to a bug in
         useradd where it doesn't honor login mappings when creating and
         populating user home directories.

7b. Walk me through 7a again?
   CLIP for RHEL 6 uses user-based access controls in SELinux.  The first 
   command, semanage, adds an SELinux user facilitating this separation and
   provides a set of roles that user is authorized to assume.  The second 
   command, useradd, actually creates the account and binds the Linux user 
   ID to the SELinux user ID.  The third command is used to set the user's 
   password.  The fourth command causes the password to immediately expire 
   thus forcing the user to set a new password on their first login.

8. How do I add categories to a user?

   After the clip installation completes, you will want to set the SELinux
   categories for privileged users.  This can be accomplished by running the
   following commands in order:
   
   # export username=`whoami`
   # sudo -Es
   # setenforce 0
   # semanage user -m -L s0 -r s0-s0:c0.c1023 ${username}_u
   # semanage login -m -s ${username}_u -r s0-s0:c0.c1023 ${username}
   # exit
   # exit

   After logging back in, running 'id -Z' should produce following the output:
   
   # <username>_u:staff_r:staff_t:s0-s0:c0.c1023

9. How do I become a privileged user?
   Use "sudo -s".  Make sure the user has a line in sudoers like this:
    echo "<USERNAME>        ALL=(ALL) ROLE=sysadm_r TYPE=sysadm_t      ALL" >> /etc/sudoers
   Note: You will have to adjust the ROLE and TYPE fields as appropriate. For
         example, ROLE=auditadm_r TYPE=auditadm_t. 

10. Why am I getting "permission denied" when adding a user?
   You probably removed user_u from your SELinux policy.  Due to a bug in
   useradd this SELinux user *must* be present.  CLIP uses SELinux constraints 
   to strip all access from that user ID so leaving it present isn't a real
   issue.

11. Why do I have to have local yum repos?
    One of the reasons we wrote this new build and integration system is to
    ensure consistency across builds.  That is, we wanted to ensure that an ISO
    generated in 2012 could be re-generated in 2014 without any functional
    differences.  Pointing to a remote repo makes this difficult to ensure.
    mock would roll RPMs using the packages available when mock was run.  
    However, the ISOs would be built using packages available when the ISO was 
    rolled.  This is exacerbated if you refer to HTTP/FTP yum repos from the
    kickstart may lead to inconsistencies between the RPMs and the ISO.  Could
    we solve this by "wget'ing" RPMs from an HTTP/FTP repo?  Sure.  But why not
    just use SMB/NFS mounts to get access to your central yum repo server.  At
    Tresys we have dedicated repo servers for each distro variant.  They share
    those repos via NFS.  Each build system NFS mounts those servers.  It is a
    relatively painless process that has proven to lead to consistency across
    builds.  All of this said, we're open to accepting patches from the
    community that implement support for remote repos but do so in a way to still
    meets the goal of reproducable builds.

12. Why do I see a series of question marks in the output of "ls -l"?
    This is SELinux enforcing a mandatory access control security policy that
    prevents a given subject (eg sysadm) from querying the security attributes of
    a file or directory.  Assuming you have search and read permissions on the
    directory you will be able to view the filename, but that is it.

13. I get setfiles errors running semodule and/or semanage.  What is going on here?
    The likely culprit is libsemanage being configured to validate fc entries
    prior to rolling a transaction forward.  The following is the error
    message emitted when this occurs:
        /etc/selinux/clip/contexts/files/file_contexts: Multiple same specifications ...
        libsemanage.semanage_install_active: setfiles returned error code 1.
	semodule:  Failed!

    The fix for this is to disable the setfiles check in samange.conf:
        echo -e "module-store = direct\n[setfiles]\npath=/bin/true\n[end]\n" > /etc/selinux/semanage.conf
     
    If you're using a CLIP kickstart the ks handles this in response to the
    CONFIG_BUILD_ENFORCING_MODE flag.  In permissive mode this check is disabled.
    Note: I would recommend doing this only when doing development.  Errors
    like this are a sign of a policy problem that needs to be fixed.

14. What are some workflows I can use to source control my changes to CLIP and
    keep in sync with updates?
    You have several options here.  One option is to do your work in a branch in
    a checkout of the CLIP git repo.  Then when a new CLIP release is made, or you
    want to pull in a change we made in HEAD, just rebase on master.
    Alternatively checkout our git repo to use as your own, make any changes you
    want using any workflow you have WRT to git, then fetch from our upstream repo
    when necessary.

    If you're not using git for your own projects it becomes slightly more
    cumbersome.  You could import a specific revision of CLIP into your SCM,
    notate the last revision of CLIP you have in some way, and when a new CLIP
    release comes out just apply the diff between that last revision and the new
    revision to your tree.  I think this is the manual process you were referring
    to above.

    I recommend a slightly different workflow for Aqueduct/SecState.  Over the
    years at Tresys we have learned that committing pre-patched upstream code
    makes it very difficult to track.  What we now do is keep "untainted" upstream
    code for these projects and create patches to apply on top of them.  You make
    changes, generate a patch, stick the patch in
    packages/aqueduct/fix-stuff.patch, and add that patch to the RPM spec file,
    packages/aqueduct/aqueduct.spec.  This makes it easy to track changes and
    keeps the upstream sources clean.  If appropriate you can submit these
    packages to the upstream projects and hopefully it will get merged into the
    project and you can stop carrying the patch in your tree.

    One other workflow I want to mention is to simply point CLIP at a pre-rolled
    RPM or yum repo.  In that way you can use your existing build system/SCM to
    generate the package(s).

15. I get errors when running semanage to manipulate users and login mappings.
    What is the deal?
    The following error message is emitted when running:
    # semanage login -a -s foo_u foo
    libsemanage.dbase_llist_query: could not query record value
    /usr/sbin/semanage: Could not query user for foo

    It looks like a bug was introduced in:
       policycoreutils-python-2.0.83-19.21.el6_2.x86_64.rpm

    It works in version:
       policycoreutils-python-2.0.83-19.18.el6_2.x86_64.rpm

    This bug led to the introduction of a conf/pkglist.blacklist file.  Adding
    packages to that file will prevent them from being using when generating
    yum repos.  We've already added the problematic packages above to that
    list.
    
    A bug has already been filed with Red Hat.  When this issue is resolved
    the FAQ will be updated.

16. How do I get the dependencies for the host?
  RHEL:
       sudo rhn-channel --add --channel=rhel-x86_64-server-optional-6.3.z
       sudo yum install rpm-build mock createrepo repoview
  CentOS:
       sudo yum install rpm-build mock createrepo repoview

17. I am getting warnings at install time stating "some of the packages you
have selected for install are missing dependencies."  What's up?
   The tools don't do a full dep check at build time.  That is because you could
   be pointing to additional yum repos at install time via the command-line
   (etc).  If anyone knows of a method to verify deps at build time please shoot
   us an email.

   The way you fix it is by making sure the referenced package is present in
   the repos in CONFIG_REPOS.  A common cause is lacking the Optional channel
   repo when building on RHEL.  This typically results in libxslt-python dep
   errors.