This proposal addresses specific deficiencies in customizing SC manifests, and proposes enhancements to increase usability and
security.
===================================================================================================================
Section 0: Starting assumptions
Receiving SC manifests along with AI manifests by service or custom client will be the same. The current principle of basing
downloads on AI service name is assumed.
It is assumed that criteria manifests will disappear per recent AI webserver
discussions.
===================================================================================================================
Section I: basic AI server enhancements: UI and internal handling of SC manifest
1. SC manifests will be SMF manifests as well. SMF will be used for all installation settings, and the SC manifest will contain the
SMF service properties and will serve as direct input for SMF.
2. SC manifests presently require "criteria manifests" for any customization (installadm add). In the existing system, a criteria
manifest can be used to specify unique AI and SC manifests based on criteria such as IP address range, MAC address range, or a
number of different criteria that are passed from the AI client to the webserver before the webserver delivers the combined AI/SC
manifest. A criteria manifest either has an embedded SC manifest, or points to one that is embedded at the time of the "installadm
add -n <service> -m <manifest>" command. installadm will be enhanced to allow SC manifests to be named and managed separately.
Named SC manifests can then be assigned to AI services, or custom clients independently (installadm create-service/create-client).
3. (related) It is not possible to have different services or criteria manifests reference the same SC manifest persistently, such
that changes in the SC manifest would affect all services that use it. Adding named SC manifests that are referred to by name in AI
services, clients, and criteria manifests can reduce replication of SC manifests and management time.
4. SC manifests are presently stripped of user comments. This will be corrected so that the AI sysadmin can refer to comments in
the SC manifest for help with modifying it, and so an AI sysadmin can add his/her own comments for the end user.
Section Ia: Manage named SC manifests:
There will be a separate command set for managing named SC manifests. installadm options for create-service, create-client, and add
subcommands will have an optional named SC manifest.
installadm create-sc -n <name> -i <file> create SC named manifest with one (or
more?) files
installadm replace-sc -n <name> -i <file> replace any existing SC file(s) with
new one(s)
installadm delete-sc -n <name> [-f] delete with option to force deletion despite referrers (subsequent use of referrer results in
either use of default manifest or perhaps error)
installadm export-sc <name> writes named SC manifest to stdout
installadm list-sc [<name>] [-n <service>] lists SC manifest and metadata,
services referencing it
(for consideration) installadm edit-sc -n <name> edit SC manifest in $EDITOR
Section Ib: use named SC manifests:
installadm create-service ... [-s <SC manifest name>] - associate named
manifest
installadm create-client ""
installadm modify-service (new) ""
installadm modify-client (new) ""
installadm modify-service/-client ... -S dissociate any named manifest
(restore to default SC manifest)
(assumed deprecated: installadm add)
Default SC manifest: an SC manifest file will be supplied with each image. It will be used when a named SC manifest is not provided
in create-service/create-client as such:
--- A named manifest with the same name as the service or custom client will be
automatically created from the image default SC manifest
--- If the name already exists, the user will be informed that an SC manifest
of the same name already exists and will be associated
--- SC manifest image default can be edited by user with 'installadm edit-sc -I
<image_path>'
Advantages of default SC manifest:
- image SC manifest default will be consistent with its image in syntax and
properties
Disadvantages:
- potential for confusion when user creates a service/client and the name
conflicts
Note on missing manifest information: if any required sysconfig properties are missing from a manifest upon first boot, the user is
prompted for them.
Implementation detail: if a custom client is created without an associated named manifest, the image default will be applied,
creating a manifest named after the custom client, and the user will receive a notice to that effect.
Section Ic: separate AI and SC manifests
An unresolved issue in the current design is the combined manifest having two different formats for AI and SC manifests. The
workaround taken was to encapsulate the SC manifest in comments, which makes it syntactically impossible for it to have its own
comments.
Advantages of a single default.xml:
- AI webserver needs only to serve a single static document for the default
case, so http efficiency is maximized
- user only has to edit a single document for AI and SC manifest defaults
Disadvantages:
- Validation of default.xml would require a tool to split and validate the AI
and SC manifest documents separately
Advantages of SC manifest in comments:
- default.xml is a valid XML document
- default.xml can be validated by an RNG schema
Disadvantages:
- SC manifest can't have its own internal comments
- SC manifest can't be validated without special tool to first extract it
I propose that default.xml be separated into AI and SC manifest default
documents per image.
Advantages:
- documents are valid and can be parsed and validated individually without
manipulation
- useless tags ai_criteria_manifest, ai_embedded_manifest, sc_embedded_manifest
and their closing tags disappear
Disadvantages:
- AI web server must dynamically merge the documents for the default case
(mitigated by the small size of the documents)
- user has 2 default documents to maintain (mitigate this by supplying commands
to help the user edit them)
Propose that the AI and SC manifests be encoded in MIME multipart. It allows us to change encoding on the server side without
having to change the client - the client would just decode it according to the header info. Also, if more information were added to
the download, it could more easily be bundled and parsed using MIME standard routines. MIME parts can be separated using a normal
text editor.
Section Id: Unnamed SC manifests - excluded from proposal:
Presently, SC manifests are not named, and are embedded with AI manifests in the
"combined manifest".
Advantages of these private, unnamed manifests:
- user creates SC manifest in 1 step
- user doesn't have to come up with a name that is used in only one instance
Disadvantages:
- complicates logic, implementation, defaulting in case of conflicts
It was decided that the disadvantages outweighed the advantages, and that the
feature can be added later.
Section Ie: Miscellaneous suggestions for enhancements:
1. SMF is expected to support multiple SC manifest files. The proposed design does not leverage this capability for AI, since a use
case was not found and managing multiple SC manifest files is more complicated.
2. There is no facility for the inclusion of data from different locations - a single manifest with no external references is
required. The user is free to use techniques to pre-process a manifest, but a front-end would help the user organizationally and
provide feedback and validation during the editing phases. Proposed (below) are some solutions involving inclusion (XInclude) and
derivation.
3. There is no semantic validation of SC manifests to catch input errors that might otherwise not be detected until after the first
boot. The DTD schema validation is very basic offering only rudimentary syntax checking. Although there are disadvantages in
having AI perform semantic validation (code not part of ON consolidation, errors in the validation code resulting from changes in
SMF properties and validation code not updated accordingly), it would be useful for users to at least be warned about invalid input
while composing the SC manifest. This is offered as an idea for discussion and is not mentioned elsewhere in this proposal.
4. There is no version control of SC manifests. Metadata including information
about pertinent versions stored in the database:
- installadm binary or package version used for "create-service"
- some kind of identifier on ISO used in "create-service"
- version of DTD schema originally validated against
can inform an upgrade script of necessary changes so that upgrades can be automated. This is offered as an topic for discussion,
and is not mentioned elsewhere in this proposal.
Section If: Caveats in proposed changes:
1) In naming manifests, if user is not attentive of other services/clients using the named manifest, changes could result in
unexpected results. An option to copy the info from the named manifest, saving it as a private unnamed manifest for the
service/client in question could break the link while supporting reuse of a single named manifest.
2) Presently, all manifests are static in a single file for maximum efficiency. Dynamic server technology would be needed. A small
amount of overhead might be added to fetch the SC manifest separately.
3) Secure client authorization could require the installing user to supply some combination of keys, certificates, passphases, or
username/password shortly after the Automated Install is initiated. These might be provided with removable media, they might be
included on the installation media, or hand-typed. (Addressed in Security section)
4) The list of named SC manifests proposed is a flat list; users may eventually
want to be able to group them.
===================================================================================================================
Section II: Deriving SC manifests
There has not been much discussion about deriving SC manifests, but it seems clear that some form of generating SC manifests could
simplify or automate the install process.
Options for derivation might include:
a) use of XInclude to import SC manifest properties from other files or objects within files: http://www.w3.org/TR/xinclude/
(support for this is proposed)
b) use of document template engines to dynamically build SC manifests, e.g. Cheetah http://www.cheetahtemplate.org/index.html (see
http://en.wikipedia.org/wiki/Template_processor) (offered as a suggestion for users)
c) user-provided script that outputs the SC manifest to stdout (proposed)
d) AI client-side insertion of properties that are not known until the AI
client boots (e.g., through DHCP) (proposed)
Derivation could take place at any of the following places in the install
process:
I) when the installadm command to create or modify the named manifest is issued
(static)
II) when the SC manifest is downloaded, run by the AI webserver (dynamic on
server)
III) after the SC manifest template is downloaded, on the AI client, based on
information not available elsewhere (dynamic on client)
XInclude (a) is a W3C standard, offering a high level of stability, reliability, and support. XInclude files are reusable.
Inclusions are first performed, then the SC manifest is validated as a DTD document. The main disadvantage is that XInclude,
although table-driven, is not dynamic in itself. xmllint(1) can perform XInclude inclusions, then validate and output the final SC
manifest.
RE: template engines, e.g., Cheetah (b) would allow the user to run a script to derive SC properties, then insert them into an SC
manifest document based on templates before being saved by installadm (I) or uploaded by the AI webserver (II). For example, if IP
address, hostname, and root password were set as replacement tags in the template, a script could fetch them at once and insert them
into the SC manifest to maintain the association. (b) would be dynamic, but perhaps more likely to fail and less predictable -
especially if run by the AI webserver (II). If Cheetah, e.g., were used on the AI client for (III), it could operate on data not
known outside of the AI client, but it would have to be installed on the AI client. JavaServer Pages (JSP) might also be used for
(II), and has the advantage of being well-established and perhaps modified for this purpose, whereas Cheetah is not standardized.
Cheetah is currently available by the IPS publisher, contrib.opensolaris.org. Template engines are mentioned here as a way for the
user to create many different SC manifests from a single SC manifest template - this is orthogonal to AI and mentioned here only as
a suggestion.
User-provided scripts are the most flexible but perhaps the most likely to fail due to user error, especially if run by the
webserver (II) or on the AI client (III).
It should also be mentioned that criteria-based manifests is currently a way to transmit AI client information to the AI webserver,
which mitigates the need for SC derivation on the AI client (III). This information could be passed to a template engine (b) for
dynamic SC manifest generation. In recent discussions, it was proposed that at install time, any information from the client would
be sent via the QUERY_STRING in the HTTP GET. This information could be provided as input to a user-defined script or document
generator. The main disadvantage of this is that this information would need to be standardized for consistent use by users.
For (d), information not available to the AI server, but available on the AI client in some circumstances could be quite useful and
could reduce the need for other derivations or multiple SC manifests on the AI server. The most prominent example is hostname: the
AI client could take the hostname assigned by DHCP and use that as a permanent hostname as an SMF property. DHCP in general is a
source for other such information, including timezone, NTP server (although not an SMF property). (see
http://www.networksorcery.com/enp/protocol/bootp/options.htm for more DHCP options - some not supported by Solaris DHCP). There are
different ways in which this might be implemented:
- if the property is missing in the SC manifest, AI client tries to use DHCP to
provide it
- sysadmin enters a replacement tag in the property value to cue the AI client
to try to derive it
Hostname derivation alone might be sufficient cause for this feature, and it might also be its only really useful case. Propose
that if the user places the text "[derived]" in the value for the hostname property, the AI client will use DHCP to derive it
(failing that, halt the installation). (Document generators would be good for this sort of thing, although perhaps excess baggage
for the AI client.)
Use case for (d): DHCP provides the hostname and there is no need to have it in
an SC manifest as well.
Proposed:
- use of XInclude (a) performing inclusions and validation when the named SC
manifest is created or modified (I)
- use of (d) to pull in DHCP hostname, etc. on AI client
Suggested:
- use of user-defined scripting (c) when the named manifest is created (I)
(user script could call a template engine (b))
For consideration:
- adding support for (a,b,c) on the AI webserver to be run dynamically at
install time (II)
- For AI client-side derivation (III), I would first hear use cases before
proposing anything.
- An SC manifest option to test XInclusion or derivation would make the process
more predictable and less risky (AKA dry run).
Section IIa: Use cases for named and derived SC manifests
Use cases for Section II are provided here. Note that not all are proposed,
but offered for review and discussion.
Use case 1:
- sysadmin has several departments with different system identification needs
- sysadmin periodically wants to use AI to install systems from different
departments
Solution: named SC manifests
Procedure:
-- sysadmin creates a named manifest for each department with appropriate name
Benefits:
-- manifest is managed by installadm so sysadmin doesn't have to keep track of
manifests
-- sysadmin changes only one manifest to effect subsequent installs for entire
department, no matter how the manifest is used
Use case 2:
- site has many systems on different subnets and wants to manage them centrally
by one sysadmin due to budget cuts
- sysadmin wants to manage SC manifests by department
- one department does testing only and wants known root and primary user
passwords
- an other department will have personal workstations that are secure and have
private root and primary usernames/passwords
Solution: (a) XInclude
Procedure:
- sysadmin uses installadm create-service to create two different services
- sysadmin uses DHCP tables to associate different services with different
subnets
- sysadmin creates named SC manifests by department
- sysadmin creates an XInclude xml file for the test systems that contains:
-- test system username/password, root password
-- xinclude pointing to the rest of the propeties common to both departments
- sysadmin creates another XInclude xml file for new private systems containing:
-- provisional root password and user account name/password that will be
changed by the private user
-- reuses the xinclude pointing to the rest of the properties
- sysadmin edits only one file to change all subsequent SC manifests for entire
department
- sysadmin runs installadm for new system(s)
- sysadmin deletes xml files containing passwords
Benefits:
- only 2 SC manifest files to maintain
- only 1 SC manifest fragment to specify passwords, which is deleted for
increased security
Use case 3:
- site just got 10 new computers
- boxes are inventoried and MAC addresses are learned
- sysadmin wants secret passwords to be automatically installed for each system
Solution: (a) XInclude
- sysadmin puts a table of MAC addresses and passwords into an XIncluded file
- sysadmin uses create-client for the MAC addresses and uses the master
XInclude file which:
-- uses the XInclude xpointer attribute to index by MAC address into the table
to fetch the passwords
-- for the rest of the SC manifest, the sysadmin uses an identical SC manifest
Benefits:
- only two SC manifest files are necessary for all install clients
- only sysadmin knows passwords
Use case 4:
- 10 new computers - same as above, except sysadmin knows how to use Cheetah
and doesn't like clumsy XInclude syntax
Solution: (b) Document template engine
Procedure:
- sysadmin makes spreadsheet - 1 line for each computer - each line is <MAC> <root password>
<user name> <user password> <etc...>
- sysadmin makes an SC manifest template where root password, user name, and
user password are represented as template variables
- sysadmin associates Cheetah SC manifest-generating script with custom client
- installadm create-client calls Cheetah engine, with MAC address as parameter
- Cheetah engine, indexes the spreadsheet by MAC and substitutes in any desired
SC manifest properties
Benefits:
- upon AI, systems have known unique passwords (and any other SC manifest
properties)
- sysadmin only edits the spreadsheet for new systems
- single copy of AI manifest template
- messy, fragile XML syntax of SC manifest avoided
Drawbacks:
- sysadmin must learn Cheetah document engine principles and basics
Use case 5:
- same as for (b), except that the sysadmin is confident with scripting abilities and wants to configure everything, then wait until
the computers arrive and the MAC addresses are known before composing the spreadsheet
Solution: (b) & (II) - dynamic SC manifest generation with document template
engine
Procedure:
- instead of creating custom clients, sysadmin leverages criteria-based manifests (installadm add) and uses the MAC address
retrieved by the webserver as input to the script that generates an SC manifest with specific passwords for specific systems
- sysadmin makes dummy table and uses dry-run option to test it
- when computers arrive, sysadmin updates table with MAC addresses and
distributes computers to installing users
- user runs AI and corresponding SC manifest is generated and used
Benefits:
- sysadmin can configure spreadsheet at the last minute and doesn't need to
re-run installadm
Use case 6:
- sysadmin wants to generate N virtual boxes using a range of static IP
addresses
- sysadmin wants to automatically generate passwords that only the sysadmin
knows
Solution: (c) custom scripting
Procedure:
- sysadmin writes script that generates an SC manifest that:
--- inserts the latest IP address in the manifest
--- generates a password
--- encrypts the password
--- supplies the IP address and encrypted password for input to a Cheetah script that inserts them into according to the SC manifest
template
--- writes a private copy of the generated password and IP address to a database
--- increments the IP address for the next install
Benefits:
- sysadmin has computers with known passwords and IP addresses and doesn't have
to compose IP addresses
Use case 7:
- sysadmin wants to install OpenSolaris on N virtual boxes using a range of
static IP addresses
- sysadmin wants to dynamically generate passwords that only the sysadmin knows
Solution: (c) and (II) install-time user-defined script
Procedure:
- sysadmin composes a standard SC manifest template with a replacement tag for
IP address and root password
- sysadmin writes a script that automatically generates an SC manifest when OpenSolaris is installed. When AI requests the SC
manifest, the script follows this algorithm:
--- finds the last IP address allocated and increments it for the new system
--- generates a password
--- encrypts the password
--- supplies the current IP address and encrypted password as input to Cheetah, which replaces the IP address and encrypted password
according to a SC manifest template
--- writes a private copy of the generated password and IP address to a database
--- outputs the SC manifest with the IP address and encrypted password
Benefits:
- as a result, sysadmin has computers with known passwords and IP addresses
- sysadmin doesn't have to compose IP addresses or passwords or prepare any
tables or configure DHCP
- passwords are securely filed
Drawbacks:
- relies on users' ability to script
- bugs, deficiencies in user script
- failed AI can foil algorithm
Possible remedy:
- concept of AI install as a transaction whose success or failure can feedback
to the AI server
Use case 8:
ISP wants to provide a service to install systems for companies, whose
configurations can drastically vary:
Solution: (c) user provides scripting for large, complex situations
- the companies provide information for sysconfig, IP addressing, etc.
- ISP creates named manifests for the companies, further subdividing them per
specific requirements
- ISP uses installadm create-service for different companies using named
manifests
Benefits:
- ISP can tailor SC manifest generation scripts according to potentially
complex user needs\
- scalable - sysadmin doesn't have to manage large number of SC manifests
Drawbacks:
- sysadmin scripting skills
- possible bugs, deficiencies in scripting
- potentially complex debugging
Section 2c: Caveats with XInclude and derivation:
2c1: XInclude resolution SC manifest caveat:
There is some potential for confusion about when the XInclude resolution occurs. Proposed: XInclude resolution occurs when the named
manifest is created or modified.
However, the user may think that XInclude resolution occurs:
-when the named manifest is associated with a service or client
-at install time
Example of incorrect usage:
Procedure user follows:
1) user leverages XInclude to include a common fragment
2) uses the included fragment to create a named manifest,
3) associates the named manifest, then
4) changes the included manifest fragment
User Expectations:
- change is integrated for installed computer
Actual Result:
- change is not integrated
A similar confusion can occur when 2) and 3) are exchanged - the user modifies
the fragment, then assigns the named manifest.
2c2: Dynamic derivation SC manifest caveats
The main caveat is that a user-defined script or document engine glitch results in AI server failure - http response code 500 with
possibly no useful reason code for debugging.
===================================================================================================================
Section III: Security
There are some basic security vulnerabilities.
-File and directory protection attributes should be set so that the SC
manifests cannot be read by everyone.
More care in setting the file protection is needed.
-The SC manifests can be downloaded by anyone who can properly formulate the
HTTP request in a web browser.
-Although passwords are encrypted in SC manifests, they can be decrypted.
-There is no network encryption. There is no client authentication.
These can be corrected with some basic SSL/TLS support (keys,
certificates, one- or two-way authentication).
Since manifests are served using web technology (http, apache, cherrypy), associated security protocols (https, SSL, TLS) can be
leveraged to increase security. For any of:
- all web servers
- a web server for a particular service or client
the webserver:
- redirects the request to https
- requires the client to provide any of:
-- key
-- certificate
-- certificate authority (for private certificate authorities)
-- username/password (physically typed)
Section IIIa: Deciding on security features:
Customer needs should be assessed as part of adding security features. Some users will want to have very high security from AI if
the installation goes out over the Internet or other insecure network. The actual interest in this use case should be researched.
In any event, degrees and particular security features can be offered to customers from which they can choose. Part of this task is
equipping the AI client with the ability to provide any private information in a flexible and reasonably convenient manner.
A basic list of possible security features:
- encryption - nullifies net snooping and exposing user account information in
the SC manifests
- one-way authentication (server-only) - the AI client is guaranteed that the SC manifest is from the intended AI server (no
accidental or falsified AI servers - probably not interesting for most users)
- two-way authentication (both client and server authenticate each other) - the AI client must provide proof that it is authorized
to receive the SC manifest in the form of a key, a certificate, passphrase, or a username/password
The security system should be open to integration with 3rd party security solutions, such as what might be offered by smart cards,
as use cases are presented.
Section IIIb: security - what would wanboot do?
http://docs.sun.com/app/docs/doc/821-0439/wanboottasks2-82?l=en&a=view
http://docs.sun.com/app/docs/doc/817-5504/6mkv4nh75?l=en&a=view#waninstalltasks-9
To provide two-way authentication, wanboot requires two keys to be input by the
user on the client:
ok set-security-key wanboot-hmac-sha1
b482aaab82cb8d5631e16d51478c90079cc1d463
ok set-security-key wanboot-3des
9ebc7a57f240e97c9b9401e9d3ae9b292943d3c143d07f04
One problem with this is that they must be hand-typed if only a console is available. The keys cannot be memorized for the average
human and must be recorded, which is a possible security hazard. Other approaches should be considered:
- sysadmin provides install medium with keys already on the medium
- Apache username/password support is leveraged
- user provides keys from files on removable media that has been securely
prepared and handled.
Security had been addressed in a discussion about AI webserver enhancements
(unclear if it will continue):
http://opensolaris.org/jive/thread.jspa?mess ageID=483344񶀐
Section IIIc: a beginning proposal for security
Propose enhancing installadm to provide HTTPS:
- protection for secure files and directories
--- identify them
--- check file ownership, protection
https - everything is encrypted to avoid net snooping
- server authentication - client identifies the server
--- server key
--- server certificate
--- certificate authority file - user can use external certificate authority or
create own certificate authority
- client authentication - server identifies the client
--- client key
--- client certificate
--- certificate authority file
Propose a system resembling the /etc/netboot hierarchy, where keys and certificates are placed on the server in locations that
protect files in that directory and all subdirectories. Top-level keys and certificates protect everything under them. Keys and
certificates at a path identifying a corresponding to AI service (or custom client) protects the AI service (or custom client). For
example, in wanboot, to protect a particular MAC address on a particular network, the keys and certificates are placed on the
netboot hierarchy at: /etc/netboot/<net ip>/<MAC>. Propose that <net ip>/<MAC> be replaced by <service name> or <MAC> in the AI
hierarchy.
Section IIId: additional security notes
George Davis has been so kind as to post a script to automate the generation
and placement of the keys and certificates:
http://www.sun.com/bigadmin/jsp/descFile.jsp?url=descAll/solaris_wanboot_set
He has also given me an updated version.
There is an additional benefit in HTTPS worth mentioning: there is an another level of error checking that might find data
communication errors that might not otherwise be corrected.
The notion of client authentication opens another possibility for SC manifests: a specific user can be identified via the client
certificate, and the user receives an SC manifest based on that identity instead of other criteria, such as AI service or MAC
address. For example, if a client certificate is used for a specific installing user, an SC manifest named after that user could be
automatically sent without the need for a custom client. This is not proposed - just offered for consideration.
HTTP GET request security: if the HTTP QUERY_STRING is used to send AI client information, the information in that string must be
evaluated in terms of security, since the HTTP GET request can be snooped. If any sensitive information is identified, the GET
request must be issued via HTTPS, which will affect such things as the URL specified in the -B install_service kernel option in
GRUB. If the QUERY_STRING is deemed not sensitive but the SC manifest payload is sensitive, a simple redirection from http->https
can be done by the webserver.
===================================================================================================================
Appendix I: Database changes
Per recent discussions, it is expected that the databases for different services be merged into a single database table, which would
be indexed by service or custom client name (or something very similar in effect). This "AI service table" would be enhanced to
include a new entry:
- sc_manifest - the associated SC manifest name - used as index to table
"sc_manifest"
A separate table for named SC manifests will be used:
Table "sc_manifest" contains fields:
- name - name of SC manifest
- path - path to SC manifest
- metadata - any associated metadata such as "creation date", "modification
date", DTD schema
The separate SC manifest table might be dispensed with with in favor of a naming scheme which unambiguously maps a SC manifest name
to the file path of the SC manifest.
_______________________________________________
caiman-discuss mailing list
[email protected]
http://mail.opensolaris.org/mailman/listinfo/caiman-discuss
