The following is a complex inheritance structure to express how inheritance works in CanIt:
base:default | +--------------------------------+--------------------------------+ | | serviceprovider-com:default widgets-co-uk:default | | +---------------------------------------------+ widgets-co-uk:bob | | examplecorp-com:default othercorp-com:default | | +--------------------------+ companyname:default | | | example-org:default example-com:default companyname:bob | | +----------------+ example-com:bob | | example-org:bob example-org:sue
Let's pretend that your name is Bob. We also are going to pretend that you work for the non-profit arm of Examplecorp and your email address is firstname.lastname@example.org.
Examplecorp also has a commercial branch with the domain example.com and by chance they also employ another person named Bob. When you and the other Bob access your CanIt streams, you both go to a stream simply called 'bob'. But it is not the same stream. You and the other Bob are able to work independently; collect different mail, create different rules and have different preferences, all because you are in different realms.
Realms are used in order to differentiate domains or groups of domains in the CanIt system. It is possible that multiple domains could share the same realm in order to share all of the same rules, but then you and Bob could not co-exist given this streaming method since both of you would be trying to use the same stream. If email@example.com also belonged to you, this would be ideal, but since it is a different person in our example, we would have to change the mapping so that your stream name was something unique (typically your full email address).
The most important rules that CanIt cares about are the ones that you or your administrator apply directly to your stream. If you create a rule here that is directly opposed to other rules further up the ladder, your rule wins every time. But these rules are limited in scope to only the addresses that use your stream. Usually this is only yours, unless this is a distribution group. This means that any rules you create will not affect your coworker Sue, nor will they affect any of the other Bob's in the diagram. The best way to look at the diagram is to realize that rules can only travel down, but that rules created further down the diagram trump those created above.
Default in Your Realm
There is never going to be a case where you specify all possible rules in your own stream; in fact, it is likely that you haven't yet specified any. So where does CanIt look next? The answer is that it will look to the default rules for your Realm. These are rules that your administrator or an administrator higher up the inheritance tree has set up to apply to everyone within the example.org organization. These rules apply to you as well as Sue, but not anyone from example.com of further up.
Parent Realms and Subrealms
The lingo starts to break down a little when there are this many levels, but the important thing to note here is that example-org and example-com are referred to as subrealms within the examplecorp-com realm while examplecorp-com itself, as well as othercorp-com are both subrealms of the serviceprovider-com realm. Finally serviceprovider-com and widgets-co-uk are subrealms of the base realm.
After checking all of the rules in your realm's default stream CanIt will continue to check the default streams in each successive parent realm's default stream until it eventually finds a rule. If it finds a rule when it gets to examplecorp-com which it did not find in example-org, for example, it will record the rule and not bother looking any higher, since this rule is more important than any applied in the higher-level parents. CanIt will only check realms that you inherit from directly, however. Despite the fact that othercorp-com is higher up the tree and may have a rule you are missing, it will not be used because it is on a separate branch of the tree.
At the very top is the base realm. This houses a generic set of rules to be applied to every user within the entire CanIt cluster. For our Hosted CanIt solution these apply to all of the thousands of domains that we host. The same will be true on a smaller scale if you are served by a re-seller who hosts their own instance of our CanIt-Domain-Pro product, or if your organization hosts it's own. While this may make the base realm seem like it is very important, it's rules are only used if there is not another conflicting rule somewhere else along the inheritance tree. There are innumerable possible rules, however, and a relative few are actually defined below. This breadth of control allows the site admin the ability to react to new spamming phenomena quickly and apply rules to all users immediately.
We also offer the CanIt-Pro product which is designed to process mail for a single organization. This allows for multiple domains, but only a single realm. This, in effect, means that only the example-org realm would exist in the above diagram which itself acts as the Base with no further inheritance. You would only have your own stream's rules and those of that default stream.
How to See Your Inheritance
The diagram is as about as complex as it can possibly be to show the extent of the possible inheritance structures available in a CanIt set-up. The Bob that you have been impersonating in on the highest end of complexity. He works for a division of a larger company who is managed by a service provider, all of which is hosted by Roaring Penguin. On the opposite end there is widgets-co-uk which is a single domain hosted directly by Roaring Penguin without anything else in between.
In the WebUI there is a handy tool in the User/Stream area along the top which allows you to see where your rules are inherited from. You can access this simply by clicking the Details link beside the stream you are currently viewing. This is what we would see for example-org:bob:
example-org:bob <-- example-org:default <-- examplecorp-com:default <-- serviceprovider-com:default <-- base:default
You would use all rules defined in any of those streams with preference given from left to right. For users who have access to higher level streams, these will be hyperlinks so that you can trace the inheritance chain up if you are looking for a rule or setting. Functionality to show inherited rules within a specific stream is currently in development and should be expected some time in the 10.1.x release cycle.