[mod-vhost-ldap.git] / examples / howto-faq-example-config.ldif

##########################################################################################
##########################################################################################
############# SKIP COMMENTED LINES TO SEE PURE LDIF FILE #################################
##########################################################################################
############# If particular access combination of pattern          #######################
############# [([location+servername]|[directoryname])+username])  #######################
############# does not work, first consult actually used filters   #######################
############# presented in example vhost_ldap.conf, and then turn  #######################
############# debugging logging with apache. there's very much log #######################
############# output, including configuration and uri parsing      #######################
############# and each search filter and retrieved variables       #######################
############# processing.                                          ####################### 
##########################################################################################
##########################################################################################

##### webserver definition
dn: apacheServerName=internal,ou=virtualHosts,dc=foo,dc=bar
objectClass: top
objectClass: apacheConfig
objectClass: organization
##### object classess - for aliases and per-location auth
##### you must include these
objectClass: apacheExtendedConfigLocation
objectClass: apacheAliasesConfigLocation
o: apache
apacheServerName: internal
##### single-value
apacheDocumentRoot: /var/www/internal
##### multi-value (optional)
apacheServerAlias: www.somedomain.com
apacheServerAlias: www.internal
##### whether aliases objects search should be performed
##### for requests to this host (aliases are assigned
##### to webserver and its uri name (virtual location)
##### with this you can keep pointers to config objects assigned,
##### but turn them off for vhost - if you set next two attrs
##### to FALSE, location and aliases won't be searched for it,
##### althoug *OptionsDn exists
apacheAliasesConfigEnabled: TRUE
apacheExtConfigHasRequireLine: TRUE
##### next two are multi values, which mean you can define 
##### many aliases and many protected location for vhost
apacheAliasConfigOptionsDn: apacheAliasConfigObjectName=internal vhost alias one,ou=webAliases,dc=foo,dc=bar
apacheLocationOptionsDn: apacheExtConfigObjectName=internal vhost access control,ou=webAccess,dc=foo,dc=bar

##### heads up - access control configuration object
dn: apacheExtConfigObjectName=internal vhost access control,ou=webAccess,dc=foo,dc=bar
objectClass: organization
objectClass: top
##### required to work
objectClass: apacheExtendedConfigObject
o: apache
##### next attribute determines whether this 
##### configuration objects is of type "require valid-user" (TRUE)
##### or "Require user1 user2 user3". This is actually related
##### for user object search. if you set to true, lookup will
##### search for userobjects which are under WucBaseDn 
##### and have userobjectservername set to alias or servername
##### of current vhost, if you set to false, apacheExtConfigUserDn
##### will be processed to get userlist ("Require user1,user2,user3...")
##### Require group usergroup not implemented yet
apacheExtConfigRequireValidUser: TRUE
##### this is usually naming attribute in the tree, anyway
##### this is the value which appears in http auth prompt dialog
apacheExtConfigObjectName: internal vhost access control
##### now - in this example, this access object keep access config
##### of two kinds, per-location and per-directory. Next two
##### attributes specified per-location assignment - perlocation
##### access control will search for object which has current req servername
##### and current req Uri. It is planned to be able to specify regexp
##### as configUri and configPath, however it's not implemented yet.
apacheExtConfigServerName: internal
apacheExtConfigUri: /locationprotected
apacheExtConfigPath: /var/www/internal/protected
##### and one above is searched for every request, compared to request r->filename, 
##### no matter what's current vhost servername is. 
##### You can have any combination of these three lines including none of them.
##### this object in general actually determines authorized users for resource,
##### so you can have some userlist specification for many servernames and aliases,
##### many uris (locations), and for many directories in the same object.
##### you should only remember, that for perlocation access config
##### servername/serveralias AND extConfigUri is matched, and for perdirectory
##### only extConfigPath is searched. 
##### and the last piece of the puzzle - if requirevaliduser is set to TRUE
##### (meaning access control entry of type "Require valid-user" and any
##### userobject which have servername and uri assigned is accepted
##### if requirevaliduser is set to FALSE, (the meaning is: 
##### "<this acl objectis NOT "Require valid-user">, which actually equals to:
##### <this acl object is "Require user1 user2 user3">)
##### list of attribute values for the following directive is processed.
apacheExtConfigUserDn: apacheExtConfigUserName=pwadas,ou=People,dc=foo,dc=bar
apacheExtConfigUserDn: apacheExtConfigUserName=otherUser,ou=People,dc=foo,dc=bar
##### and, of course, you can have multiple values for this attribute
##### (final list contains multiple usernames). Remember - username "nobody" is
##### a special username, which is always appended to the result list, to avoid
##### case, when you specify extConfigRequireValidUser to FALSE and do not specify
##### any usernames (valid list <"require user" '[username] ...'> passed to apache
##### must include at list one username. so creating user object entry 
##### with extConfigUserName "nobody" is not recommended as it's always appended
##### to the list.

##### username object
dn: apacheExtConfigUserName=pwadas,ou=People,dc=foo,dc=bar
##### these object must contain one or more values for UserName attribute.
##### keeping one value which should be naming attribute is recommended,
##### however you can specify many loginnames for one user.
##### If you create two userobject entries, and both of them will have
##### attribute apacheExtConfigUserName with the value "johnny"
##### (this may be hidden if UserName is not naming attribute)
##### password will be matched ONLY against first entry found.
##### which one will be found first when lookup is done with
##### "(username=XXX)(servername=YYY)(uri=ZZZ)" is hard to predict,
##### consult with openldap documentation, and watch the filter used.
##### on the other hand - you can still have to userobjects with
##### the same names for per-location access control, and if
##### these object have different servernames - appropriate one
##### will be found.
apacheExtConfigUserName: pwadas
apacheExtConfigUserName: someotherusername
o: apache
objectClass: organization
objectClass: top
##### this is required of course
objectClass: apacheExtendedConfigUserObject
##### now - you can have multiple passwords for one userobject
##### no matter how many usernames it contains. 
##### recognized password format is cleartext, 
##### standard htpasswd-encrypted string (stored as cleartext)
##### and linux-shadowlike value stored as {CRYPT}. This means,
##### that you can combine posixAccount with webuser object,
##### if you create object with appropriate classes, and
##### userPassword attribute is the same for both classes.
##### however in such situation extendedconfigUserName is
##### still required and multi-value :-), so you'll probably want 
##### keep posixAccount's "uid" and this have at least one the same value.
##### of course this applies to any attribute which you map
##### as "uid" in libnss-ldap configuration. with mod-vhost-ldap
##### ONLY extConfigUserName is searched.
userPassword: www
userPassword: p00nQ0ftSC5cU
userPassword: {CRYPT}$1$RG.pRvZh$Q0WZ8clsqtMUBRLFckoQg1
##### one username object may contain multiple values
##### for URI's and directories. which mean you can apply
##### the same userobject to many resources. however
##### with LocationUri, appropriate configUserServername must be
##### defined to have this userobject matched with search lookup.
apacheExtConfigUserDirectoryName: /var/www/internal/protected
apacheExtConfigUserServerName: www.internal
apacheExtConfigUserLocationUri: /protecteduri/

##### and the most simple thing - aliasing object
##### ObjectName has only naming usage, if any, as aliases
##### doesn't have "prompts". however object must have some logical
##### name, and uri or target is not a good choice - first because
##### it always contain at least one "/", and second - it can
##### have many values for sourceUri, so specifying it as naming
##### attribute will always mask other values. 
dn: apacheAliasConfigObjectName=internal vhost alias one,ou=webAliases,dc=foo,dc=bar
objectClass: organization
objectClass: top
objectClass: apacheAliasConfigObject
o: apache
apacheAliasConfigObjectName: internal vhost alias one
##### you can alias multiple uri's to one physical directory
apacheAliasConfigSourceUri: /abcd/x
apacheAliasConfigSourceUri: /some/url/anywhere
##### remember - for aliases to work, you must specify at least
##### one servername, as aliases (virtual uri's) are always
##### related to virtualhost. anyway, if you specify multiple
##### servername, the result will be the same uri for many
##### virtualhosts, assigned to the same physical directory.
##### with multiple servername, the same issues applied
##### as with multiple loginnames - if it's not naming attribute
##### you may get messed with many objects describing the same
##### uri for the same vhost (multiple pairs for uri+servername).
##### in this case first one found will be returned applied.
##### (lookup is done in the way which returns ONE entry only).
##### original mod_alias supports regular expression to specify
##### this, in modvhostldap regexp is not supported yet.
##### it's planned to be able to define regexp for servername and uri,
##### and this will be even more flexible than original, as
##### with original you can have regexp for uri only, and vhost
##### is determined by context to which directive AliasMatch apply.
apacheAliasConfigServerName: internal
apacheAliasConfigServerName: www.someotherhost.com
##### target dir is single-value. It could be multiple-value,
##### to be able to store different pairs with one object, however
##### on the other hand specifiying two or more physical directories
##### for one URI doesn't make much sense, so to avoid mess
##### it's single value.
apacheAliasConfigTargetDir: /var/www/internal/protected
##### and that's all folks :)
Commit	Line	Data
2ca64e63 PW	1	##########################################################################################
	2	##########################################################################################
	3	############# SKIP COMMENTED LINES TO SEE PURE LDIF FILE #################################
	4	##########################################################################################
	5	############# If particular access combination of pattern #######################
	6	############# [([location+servername]\|[directoryname])+username]) #######################
	7	############# does not work, first consult actually used filters #######################
	8	############# presented in example vhost_ldap.conf, and then turn #######################
	9	############# debugging logging with apache. there's very much log #######################
	10	############# output, including configuration and uri parsing #######################
	11	############# and each search filter and retrieved variables #######################
	12	############# processing. #######################
	13	##########################################################################################
	14	##########################################################################################
	15
	16	##### webserver definition
	17	dn: apacheServerName=internal,ou=virtualHosts,dc=foo,dc=bar
	18	objectClass: top
	19	objectClass: apacheConfig
	20	objectClass: organization
	21	##### object classess - for aliases and per-location auth
	22	##### you must include these
	23	objectClass: apacheExtendedConfigLocation
	24	objectClass: apacheAliasesConfigLocation
	25	o: apache
	26	apacheServerName: internal
	27	##### single-value
	28	apacheDocumentRoot: /var/www/internal
	29	##### multi-value (optional)
	30	apacheServerAlias: www.somedomain.com
	31	apacheServerAlias: www.internal
	32	##### whether aliases objects search should be performed
	33	##### for requests to this host (aliases are assigned
	34	##### to webserver and its uri name (virtual location)
	35	##### with this you can keep pointers to config objects assigned,
	36	##### but turn them off for vhost - if you set next two attrs
	37	##### to FALSE, location and aliases won't be searched for it,
	38	##### althoug *OptionsDn exists
	39	apacheAliasesConfigEnabled: TRUE
	40	apacheExtConfigHasRequireLine: TRUE
	41	##### next two are multi values, which mean you can define
	42	##### many aliases and many protected location for vhost
	43	apacheAliasConfigOptionsDn: apacheAliasConfigObjectName=internal vhost alias one,ou=webAliases,dc=foo,dc=bar
	44	apacheLocationOptionsDn: apacheExtConfigObjectName=internal vhost access control,ou=webAccess,dc=foo,dc=bar
	45
	46	##### heads up - access control configuration object
	47	dn: apacheExtConfigObjectName=internal vhost access control,ou=webAccess,dc=foo,dc=bar
	48	objectClass: organization
	49	objectClass: top
	50	##### required to work
	51	objectClass: apacheExtendedConfigObject
	52	o: apache
	53	##### next attribute determines whether this
	54	##### configuration objects is of type "require valid-user" (TRUE)
	55	##### or "Require user1 user2 user3". This is actually related
	56	##### for user object search. if you set to true, lookup will
	57	##### search for userobjects which are under WucBaseDn
	58	##### and have userobjectservername set to alias or servername
	59	##### of current vhost, if you set to false, apacheExtConfigUserDn
	60	##### will be processed to get userlist ("Require user1,user2,user3...")
	61	##### Require group usergroup not implemented yet
	62	apacheExtConfigRequireValidUser: TRUE
	63	##### this is usually naming attribute in the tree, anyway
	64	##### this is the value which appears in http auth prompt dialog
65	apacheExtConfigObjectName: internal vhost access control
66	##### now - in this example, this access object keep access config
67	##### of two kinds, per-location and per-directory. Next two
68	##### attributes specified per-location assignment - perlocation
69	##### access control will search for object which has current req servername
70	##### and current req Uri. It is planned to be able to specify regexp
71	##### as configUri and configPath, however it's not implemented yet.
72	apacheExtConfigServerName: internal
73	apacheExtConfigUri: /locationprotected
74	apacheExtConfigPath: /var/www/internal/protected
75	##### and one above is searched for every request, compared to request r->filename,
76	##### no matter what's current vhost servername is.
77	##### You can have any combination of these three lines including none of them.
78	##### this object in general actually determines authorized users for resource,
79	##### so you can have some userlist specification for many servernames and aliases,
80	##### many uris (locations), and for many directories in the same object.
81	##### you should only remember, that for perlocation access config
82	##### servername/serveralias AND extConfigUri is matched, and for perdirectory
83	##### only extConfigPath is searched.
84	##### and the last piece of the puzzle - if requirevaliduser is set to TRUE
85	##### (meaning access control entry of type "Require valid-user" and any
86	##### userobject which have servername and uri assigned is accepted
87	##### if requirevaliduser is set to FALSE, (the meaning is:
88	##### "<this acl objectis NOT "Require valid-user">, which actually equals to:
89	##### <this acl object is "Require user1 user2 user3">)
90	##### list of attribute values for the following directive is processed.
91	apacheExtConfigUserDn: apacheExtConfigUserName=pwadas,ou=People,dc=foo,dc=bar
92	apacheExtConfigUserDn: apacheExtConfigUserName=otherUser,ou=People,dc=foo,dc=bar
93	##### and, of course, you can have multiple values for this attribute
94	##### (final list contains multiple usernames). Remember - username "nobody" is
95	##### a special username, which is always appended to the result list, to avoid
96	##### case, when you specify extConfigRequireValidUser to FALSE and do not specify
97	##### any usernames (valid list <"require user" '[username] ...'> passed to apache
98	##### must include at list one username. so creating user object entry
99	##### with extConfigUserName "nobody" is not recommended as it's always appended
100	##### to the list.
101
102	##### username object
103	dn: apacheExtConfigUserName=pwadas,ou=People,dc=foo,dc=bar
104	##### these object must contain one or more values for UserName attribute.
105	##### keeping one value which should be naming attribute is recommended,
106	##### however you can specify many loginnames for one user.
107	##### If you create two userobject entries, and both of them will have
108	##### attribute apacheExtConfigUserName with the value "johnny"
109	##### (this may be hidden if UserName is not naming attribute)
110	##### password will be matched ONLY against first entry found.
111	##### which one will be found first when lookup is done with
112	##### "(username=XXX)(servername=YYY)(uri=ZZZ)" is hard to predict,
113	##### consult with openldap documentation, and watch the filter used.
114	##### on the other hand - you can still have to userobjects with
115	##### the same names for per-location access control, and if
116	##### these object have different servernames - appropriate one
117	##### will be found.
118	apacheExtConfigUserName: pwadas
119	apacheExtConfigUserName: someotherusername
120	o: apache
121	objectClass: organization
122	objectClass: top
123	##### this is required of course
124	objectClass: apacheExtendedConfigUserObject
125	##### now - you can have multiple passwords for one userobject
126	##### no matter how many usernames it contains.
127	##### recognized password format is cleartext,
128	##### standard htpasswd-encrypted string (stored as cleartext)
129	##### and linux-shadowlike value stored as {CRYPT}. This means,
130	##### that you can combine posixAccount with webuser object,
131	##### if you create object with appropriate classes, and
132	##### userPassword attribute is the same for both classes.
133	##### however in such situation extendedconfigUserName is
134	##### still required and multi-value :-), so you'll probably want
135	##### keep posixAccount's "uid" and this have at least one the same value.
136	##### of course this applies to any attribute which you map
137	##### as "uid" in libnss-ldap configuration. with mod-vhost-ldap
138	##### ONLY extConfigUserName is searched.
139	userPassword: www
140	userPassword: p00nQ0ftSC5cU
141	userPassword: {CRYPT}$1$RG.pRvZh$Q0WZ8clsqtMUBRLFckoQg1
142	##### one username object may contain multiple values
143	##### for URI's and directories. which mean you can apply
144	##### the same userobject to many resources. however
145	##### with LocationUri, appropriate configUserServername must be
146	##### defined to have this userobject matched with search lookup.
147	apacheExtConfigUserDirectoryName: /var/www/internal/protected
148	apacheExtConfigUserServerName: www.internal
149	apacheExtConfigUserLocationUri: /protecteduri/
150
151	##### and the most simple thing - aliasing object
152	##### ObjectName has only naming usage, if any, as aliases
153	##### doesn't have "prompts". however object must have some logical
154	##### name, and uri or target is not a good choice - first because
155	##### it always contain at least one "/", and second - it can
156	##### have many values for sourceUri, so specifying it as naming
157	##### attribute will always mask other values.
158	dn: apacheAliasConfigObjectName=internal vhost alias one,ou=webAliases,dc=foo,dc=bar
159	objectClass: organization
160	objectClass: top
161	objectClass: apacheAliasConfigObject
162	o: apache
163	apacheAliasConfigObjectName: internal vhost alias one
164	##### you can alias multiple uri's to one physical directory
165	apacheAliasConfigSourceUri: /abcd/x
166	apacheAliasConfigSourceUri: /some/url/anywhere
167	##### remember - for aliases to work, you must specify at least
168	##### one servername, as aliases (virtual uri's) are always
169	##### related to virtualhost. anyway, if you specify multiple
170	##### servername, the result will be the same uri for many
171	##### virtualhosts, assigned to the same physical directory.
172	##### with multiple servername, the same issues applied
173	##### as with multiple loginnames - if it's not naming attribute
174	##### you may get messed with many objects describing the same
175	##### uri for the same vhost (multiple pairs for uri+servername).
176	##### in this case first one found will be returned applied.
177	##### (lookup is done in the way which returns ONE entry only).
178	##### original mod_alias supports regular expression to specify
179	##### this, in modvhostldap regexp is not supported yet.
180	##### it's planned to be able to define regexp for servername and uri,
181	##### and this will be even more flexible than original, as
182	##### with original you can have regexp for uri only, and vhost
183	##### is determined by context to which directive AliasMatch apply.
184	apacheAliasConfigServerName: internal
185	apacheAliasConfigServerName: www.someotherhost.com
186	##### target dir is single-value. It could be multiple-value,
187	##### to be able to store different pairs with one object, however
188	##### on the other hand specifiying two or more physical directories
189	##### for one URI doesn't make much sense, so to avoid mess
190	##### it's single value.
191	apacheAliasConfigTargetDir: /var/www/internal/protected
192	##### and that's all folks :)