As we approach the November 2008 release, we need to plan how we will approach file layouts for platforms for which Sun Web Stack is in a "standalone profile" (a.k.a. unbundled). These platforms are expected to include Solaris 10 and some Enterprise Linux releases. File layouts for OpenSolaris are governed and reviewed via the ARC process.
Some other research leveraged in the preparation of this document are available from the GlassFish Update Center wiki. In particular, the filesystem layout recommendations. These documents are for other products dealing with a different set of constraints, but there is a goal to have consistency where possible.
There are some places where the recommendations on filesystem layout differ with the components already through OpenSolaris ARC and integrated with OpenSolaris. This plan has tried to strike a balance between those and the standards for unbundled/other platforms.
Requirements
There are several requirements for this release after significant consideration. These will constrain the options.
- Sun Web Stack MUST follow packaging guidelines for Solaris 10, including those allowing for sparse zone support when using Sun Web Stack. This means delivering main binaries into /opt, configuration files into /etc/opt and variable length application data into /var/opt.
- In the case of non-native packaging, where everything is expected to be under an $INSTALL_ROOT, Sun Web Stack MUST provide utilities to populate the appropriate directories via post-install configuration on Solaris 10. The default for non-native packaging would be under the $INSTALL_ROOT.
- Sun Web Stack MUST initially deliver native package formats to all systems which are "standalone profile"
- Sun Web Stack MUST allow for installation of multiple releases of Sun Web Stack in the case of Solaris 10 non-global zones
- SMF manifests should be delivered into /var/svc/manifest (outside of $OPT_ROOT).
- SMF methods for all components will reside in the common directory $OPT_ROOT/lib/svc/method.
- RedHat init scripts should be delivered into /etc/init.d (outside of $OPT_ROOT).
Other Limitations
Sun Web Stack WILL NOT allow for installation of multiple Major releases at the same time in a given OS instance (or the global zone in the case of Solaris 10) when using native packages. The integration/testing of all of the components for a given release may not provide simple rolling forward binary compatibility.
Users desiring multiple Major releases on a single system at one time can optionally use an installation system based on the same technology in the Image Packaging System and incorporated in the Sun Software Update Center. All components will need to be built relative to the installation root. This is expected to be available in early 2009.
Sample Paths
Assume a user wishes to install lighttpd 1.4.19, Apache 2.2.9 and Ruby 1.8.6-p287. This would yield the following paths on Solaris 10:
/opt/webstack
/opt/webstack/bin
/opt/webstack/bin/apxs 1
/opt/webstack/bin/pecl 1
/opt/webstack/bin/php 1
/opt/webstack/bin/ruby 1
...
/opt/webstack/lib
/opt/webstack/lib/svc/method
/opt/webstack/man
/etc/opt/webstack
/var/opt/webstack
...
/opt/webstack/lib/libaprutil-1.so.0.2.12 (do we need APR libs versioned?)
/opt/webstack/apache2/2.2/bin/httpd
/opt/webstack/apache2/2.2/lib/...
...
/opt/webstack/lighttpd/1.4/sbin/lighttpd
/opt/webstack/lighttpd/1.4/lib/...
/opt/webstack/lighttpd/1.4/man/...
...
/opt/webstack/ruby/1.8/bin/ruby
...
/etc/opt/webstack/apache/2.2/httpd.conf
/etc/opt/webstack/lighttpd/1.4/lighttpd.conf
...
/var/svc/manifest/apache22
/var/svc/manifest/lighttpd14
1. The symlink would stay 'stable' for a given release of Sun Web Stack. In other words, it would always point to the same version initially shipped in that Sun Web Stack major version. In other words, if it were to point to ruby 1.8 in Sun Web Stack release 1.4, it would continue to do so for every Sun Web Stack 1.x release. Ruby 1.9 may be introduced with incomptibilities, but it would be in a separate path. The end user may have to reference that path explicitly and/or reconfigure components to use the newly delivered incompatible component.
The layout above would be exactly the same on Linux except that "/opt/webstack" would be replaced with "/opt/sun/webstack" to avoid collisions and to follow Sun standard layouts on Linux.
OS bases can be described as the following
| OpenSolaris | Solaris 10 | Linux | |
|---|---|---|---|
| $OPT_ROOT | /usr/ | /opt/webstack/ | /opt/sun/webstack/ |
| $VAR_ROOT | /var/ | /var/opt/webstack/ | /var/opt/sun/webstack/ |
| $ETC_ROOT | /etc/ | /etc/opt/webstack/ | /etc/opt/sun/webstack/ |
It is possible that a future release of the Sun Web Stack may deliver multiple two major/minor releases of the same component. Ideally this would not happen, but we recognize that not all upstream components maintain sufficient binary compatibility across minor releases. The inclusion of an incompatible component in a Sun Web Stack minor release would be an exception case and considered on a case-by-case basis.
For example, Ruby is expected to make changes between Ruby 1.8 and 1.9. Assume for a moment Apache delivered changes in binary compatibility between 2.2 and 2.4. Then a user who would, for instance, update from Sun Web Stack 1.4 to 1.6 would have a layout similar to the following on Solaris 10:
/opt/webstack
/opt/webstack/bin
/opt/webstack/bin/apxs 1
/opt/webstack/bin/pecl 1
/opt/webstack/bin/php 1
/opt/webstack/bin/ruby 1
...
/opt/webstack/lib
/opt/webstack/man
/etc/opt/webstack
/var/opt/webstack
...
/opt/webstack/lib/libaprutil-1.so.0.2.12
/opt/webstack/apache2/2.2/bin/httpd
/opt/webstack/apache2/2.2/lib/...
...
/opt/webstack/apache2/2.4/bin/httpd
/opt/webstack/apache2/2.4/lib/...
...
/opt/webstack/lighttpd/1.4/bin/lighttpd
/opt/webstack/lighttpd/1.4/lib/...
...
/opt/webstack/ruby/1.8/bin/ruby
...
/opt/webstack/ruby/1.9/bin/ruby
...
/etc/opt/webstack/apache2/2.2/httpd.conf
...
/etc/opt/webstack/apache2/2.4/httpd.conf
...
/etc/opt/webstack/lighttpd/1.4/lighttpd.conf
...
This has created a ruby/1.9 and apache2/2.4 $COMPONENT_ID set of directories. In this example, because an incompatibility is significant in the upstream minor release, a new directory will be introduced. As stated earlier, this is an exception case. This can cause confusion, so this is not an option to be considered lightly. Where there are incompatibilities, the preference would be to wait for the next Sun Web Stack major release (which should be <18 months away, and in many cases much less).
Notes on the sample Paths
In general, this layout follows section 2.2 of the "Filesystem Layout for Unbundled Software: Best Practices and Requirements". One exception to this is that the base on Solaris 10 delivers to /var/opt/webstack and /etc/opt/webstack The components delivered are built with these paths in mind and in the IPS packaging scenario, there MUST be configuration utilities that create and populate these paths. This allows for support of Solaris zones in Solaris 10, and provides consistency across other platforms.
The /opt/webstack directory provides a directory namespace for the Web Stack which will separate its installation from any other software releases. This does not follow the release guidelines of using the package name, wherein the package name is prefixed by SUNW. There are two reasons for this. First, it is expected for future Solaris releases to drop the "SUNW" namespacing for packages. Second, the SUNW prefixing is a SysVR4 convention which has been poorly received by most end users and does not apply to any OS other than Solaris 10. It should be noted that this DOES NOT prevent the packages being delivered to Solaris 10 from using a SUNW prefix.
It is recognized that in order to achieve the above layout, there will be a requirement for some type of "base package".
Changelog
- Updated sample paths based on discussion with Jyri Virkki and others on Sun Web Stack engineering team; added table for samples 15-Oct-2008
- Further updated sample paths, fixing inconsistencies in second half 20-Oct-2008
- Added coverage of SMF manifests and methods (Solaris 10). 22-Oct-2008
Comments (13)
Sep 18, 2008
dipol says:
Thanks for the opportunity to comment, and I appreciate that you took the time ...Thanks for the opportunity to comment, and I appreciate that you took the time to read the "Filesystem Layout for Unbundled Software" spec. My feedback:
"Sample Paths":
Under /opt the apache directory is qualified with a major release number (/opt/websstack/apache2), but under /etc it's qualified with major.minor (/etc/opt/webstack/apache2.2). Was this intentional? Seems like they should be consistent. Same comment for lighttpd.
"Notes on the sample Paths":
I'm a bit concerned with the first paragraph. Is this proposing that the unbundled non-native packages could be installed anywhere (good), but the binaries would have hard-coded references to look for stuff in /var/opt/webstack and /etc/opt/webstack (not so good)? This seems counter to the spirit of the unbundled/mult-install design where $INSTALL_ROOT's are fairly self-contained, fully relocatable, and mult-install capable. If I install multiple copies of the unbundled packages on my system, can I end up with clashes in /etc/opt/webstack?
Not that you're prohibited from placing data outside of your $INSTALL_ROOT. Many products do provide options for locating their dynamic data elsewhere. For example with GlassFish I can create my domains anywhere in the filesystem. That's fine. But by default we like the $INSTALL_ROOT's to be as self contained as possible, and to avoid hard-coded absolute paths to data (other than that provided by the OS).
Joe
Oct 15, 2008
mingenthron says:
In the sample paths, that was a mistake to have, for instance 2 and 2.2. I've c...In the sample paths, that was a mistake to have, for instance 2 and 2.2. I've corrected that. We've actually updated it a bit, deciding to go with the layout more like the bundled release.
Regarding the concern about the first paragraph, we're actually currently in a situation where we may not be able to deliver a relocatable Sun Web Stack for some time. It's unfortunately not as simple as building relative to a given root. Many components deliver a </I>component</I>-config script which may be used by user apps or frameworks at build/configuration time. It's certainly possible to "patch" all of these after install, but to fully test that will take some work. Some of this I've even learned subsequent to the initial proposal.
What you see there regarding /var/opt and /etc/opt will in any event just be a recommendation in docs, potentially backed up by tools. Once we have a relocatable Sun Web Stack, modifying those tools to use the relocatable root for their variable/config data is possible. It'll, of course, always be possible for someone to build their own httpd.conf/php.ini/my.cnf files and put them in any random directory of the user's choosing.
Our supported configuration until we're relocatable would be to not allow the delivery of multiple major releases of Sun Web Stack concurrently. Since we won't change a component to be incompatible with what they have in /var/opt and /etc/opt within a minor release of Sun Web Stack, there won't be cause for collision.
Sep 18, 2008
ckamps says:
As mentioned by Joe, thanks for the opportunity to provide comments. General: ...As mentioned by Joe, thanks for the opportunity to provide comments.
General:
The packaging approach doesn't really have that much to do with fixed vs relocatable, but multi-install support does. i.e. it's really hard to achieve multi-install support with native packaging (apart from the use of separate zones or OS instances).
Intro:
Other Limitations:
Notes on Sample Paths:
Zones on Solaris 10 can be supported without creating and populating these exact paths. I think what you might be trying to convey is that auto realization of /var/opt/webstack/ and /etc/opt/webstack/ doesn't happen when using IPS user images. That's correct, but this limitation is different than not being able to support zones in Solaris 10. If it was the case where user images inhibited support of Solaris 10 zones, then a whole bunch of non-SVR4 packaged software (Oracle, WebLogic, you name it) would be labelled as such. And that's certainly not the case.
For example: I set up Apache2 in a non-global zone last night in support of a project. I leveraged the binaries installed under /usr/apache2/, but I used my own consolidated location for the httpd.conf, htdocs and log files. I didn't care about the /etc/apache2/ and /var/apache2/ areas in my non-global zones. In fact, the hosting provider recommended that I colocate all of my application content in a designated area. I didn't really care what packaging approach was used to install Apache2 in the global zone. If there was a layered install of Apache2 that was accessible to me via /opt/webstack or another area propagated from the global zone, that would have been fine too.
Oct 15, 2008
mingenthron says:
Agreed with many of your saying I've mixed too much here-and-now and forward loo...Agreed with many of your saying I've mixed too much here-and-now and forward looking relocatable. Having said that, we don't want things to be completely different between the two worlds. Ideally an end user could set some variables and deal with a "standalone profile" version just as I would an "integrated profile" version. For these components, that becomes pretty important, since deployment is very different than in the Java world.
On the "layered distros" versus "integrated profile" versus "bundled", I heartilly agree that it'd be useful to settle down on one set of terms. Having said that, I'm just using what's consistent with other docs in Sun Web Stack. I'll take that recommendation that we simplify our terminology to the team.
Agreed that I should make it more clear that native package releases have no options for install locations.
Regarding the topic of zones, the main motivation for releasing packages/patches is to fit with the way enterprises already deploy their software. These may use kickstart/jumpstart or deal with creating new zones. The approach you describe, setting up your own httpd.conf and defining your own htdocs/log file directories, will most certainly work. It should, however, also work for someone to define a new zone using a shared /opt and just "svcadm enable http:apache22" to turn on Apache HTTP as a service. Further, it needs to be possible to determine the inventory and patchlevel for any given OS instance without 'special' tools.
I recognize that in GlassFish, this is very different. It is a rarity that a Java app server is delivered as a native package. For these other items, it's more common.
Sep 24, 2008
cvr says:
Thanks so much for laying out the layout! One quick comment, since the layouts ...Thanks so much for laying out the layout!
One quick comment, since the layouts for the two profiles (integrated vs standalone) differ. While the differences may not be significant, it would be nice to document the differences and explain why these differences exist.
Thanks again!
Sep 25, 2008
Seema-A says:
I think /etc/opt/webstack/ and /var/opt/webstack/ convention is little confusing...I think /etc/opt/webstack/ and /var/opt/webstack/ convention is little confusing.
Instead, wouldn't it be better to go with /etc/webstack and /var/webstack and /opt/webstack diretctory layout ?
Update: I came across this link and looks like /etc/opt/<component> and /var/opt/<component> is a common convention.
http://www.pathname.com/fhs/pub/fhs-2.3.html
Oct 20, 2008
mingenthron says:
Yes, and it's the only approach that is compatible with Solaris zones which use ...Yes, and it's the only approach that is compatible with Solaris zones which use a shared /opt and allow /var/opt and /etc/opt to be edited.
Oct 01, 2008
Jeff_Trawick_Sun says:
The "(symlink to latest version)" part disturbs me. In the case where a new, in...The "(symlink to latest version)" part disturbs me. In the case where a new, incompatible version of an open source package has to be provided before a new major product release, users should still be able to upgrade without mandatory migration work. If the symlinks they use are updated to point to the latest version, there appears to be mandatory migration work (use commands in directory containing older version of the open source package).
Oct 20, 2008
mingenthron says:
Agreed. This was changed/clarified to state that the symlink will not be update...Agreed. This was changed/clarified to state that the symlink will not be updated even when a new version of a component is introduced. This means the end user (or some utility) will need to manually select the updated component. I've further clarified the relationship with Sun Web Stack major.minor releases: the goal would be to only introduce an incompatible component in a Sun Web Stack major release. Since major releases are available pretty regularly (about every 18 months), it's not a long wait until component availability.
Oct 01, 2008
nigoroll says:
Regarding support for multiple versions I think symlinking in bin/ is unnecessar...Regarding support for multiple versions I think symlinking in bin/ is unnecessary.
"Other limitations" sais:
> Users desiring multiple Major releases on a single system at one time can (do so)
> [...] All components will need to be built relative to the installation root.
So if I get this right, I could install /opt/webstack-2008-10 as well as
/opt/webstack-2009-01 and, for instance, use an /opt/webstack symlink to
easily switch from one to another.
Config files (which, yes, should be in /etc/opt/webstack) can refer to /opt/webstack
(the symlink) only.
I have helped maintaining a (proprietary) SAMP/SAPP stack for the last couple of
years and my experience is that it is very important to provide an easy
way of "switching" webstack releases. There are a lot of interdependencies
between various components (in particular regarding the Ps and the M) and you
will regularly get incompatibilities of application code with never versions.
Cheers, Nils
Dec 11, 2008
ckasso says:
I have a couple of questions: To what degree is non-root install desired? It i...I have a couple of questions:
To what degree is non-root install desired? It is not mentioned on the page but I think it is implied by your desire to support $INSTALL_ROOT but maybe not.
One of the requirements stated above is:
``In the case of non-native packaging, where everything is expected to be under an $INSTALL_ROOT, Sun Web Stack MUST provide utilities to populate the appropriate directories via post-install configuration on Solaris 10. The default for non-native packaging would be under the $INSTALL_ROOT.''
Are the "appropriate directories" /etc and /var to support zones? Do you anticipate non-root users to be a big user of zones? It might be better to ensure the WebStack components support relocation of their config such that the can use a location in $INSTALL_ROOT, /etc or anywhere else the user desires. If a non-root user has installed the product they probably will not be able to use /etc.
Dec 11, 2008
Jeff_Trawick_Sun says:
Non-root install isn't supported in this release. We haven't made the various o...Non-root install isn't supported in this release. We haven't made the various open source features relocatable, so they are hard-wired to a particular directory, which leads to the root install requirement.
Dec 11, 2008
ckasso says:
Thanks - my question was more forward looking. The above document is about the ...Thanks - my question was more forward looking. The above document is about the "standalone" filesystem layout. I'm wondering if non-root install is a requirement (or the extent to which it is desired) as the product begins to support a standalone profile and transitions to pkg(5)/IPS packages.