bneradt commented on code in PR #12359: URL: https://github.com/apache/trafficserver/pull/12359#discussion_r2216910386
########## doc/admin-guide/plugins/realip.en.rst: ########## @@ -0,0 +1,86 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + + .. include:: ../../common.defs + +.. _admin-plugins-realip: + +Real IP Plugin +******************* + +Description +=========== +The `realip` plugin reads an IP address from a specified data source such as HTTP header field, and make it available for ATS and +its plugins as the verified client address. + +To use the verified client IP address for ACL, :ts:cv:`proxy.config.acl.subjects` needs to be set to `PLUGIN`. +Similary, if you want to use the IP address on header_rewrite plugin, its `INBOUND_IP_SOURCE` needs to be set to `PLUGIN`. + + +Configuration +============= + +To enable the `realip` plugin, insert the following line in :file:`plugin.config`: Review Comment: I think you'll need two `::` at the end to make this a code block. ########## doc/admin-guide/plugins/realip.en.rst: ########## @@ -0,0 +1,86 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + + .. include:: ../../common.defs + +.. _admin-plugins-realip: + +Real IP Plugin +******************* + +Description +=========== +The `realip` plugin reads an IP address from a specified data source such as HTTP header field, and make it available for ATS and +its plugins as the verified client address. + +To use the verified client IP address for ACL, :ts:cv:`proxy.config.acl.subjects` needs to be set to `PLUGIN`. +Similary, if you want to use the IP address on header_rewrite plugin, its `INBOUND_IP_SOURCE` needs to be set to `PLUGIN`. + + +Configuration +============= + +To enable the `realip` plugin, insert the following line in :file:`plugin.config`: + + realip.so <config.yaml> + +The plugin supports 2 mode: Review Comment: `mode` -> `modes` ########## doc/admin-guide/plugins/realip.en.rst: ########## @@ -0,0 +1,86 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + + .. include:: ../../common.defs + +.. _admin-plugins-realip: + +Real IP Plugin +******************* + +Description +=========== +The `realip` plugin reads an IP address from a specified data source such as HTTP header field, and make it available for ATS and +its plugins as the verified client address. + +To use the verified client IP address for ACL, :ts:cv:`proxy.config.acl.subjects` needs to be set to `PLUGIN`. +Similary, if you want to use the IP address on header_rewrite plugin, its `INBOUND_IP_SOURCE` needs to be set to `PLUGIN`. Review Comment: Let's link `header_rewrite` to the header rewrite plugin docs. ########## doc/developer-guide/api/functions/TSHttpTxnVerifiedAddrSet.en.rst: ########## @@ -0,0 +1,64 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed + with this work for additional information regarding copyright + ownership. The ASF licenses this file to you under the Apache + License, Version 2.0 (the "License"); you may not use this file + except in compliance with the License. You may obtain a copy of + the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing + permissions and limitations under the License. + +.. include:: ../../../common.defs + +.. default-domain:: cpp + +TSHttpTxnVerifiedAddrSet +************************ + +Sets a client IP address verified by a plugin. + +Synopsis +======== + +.. code-block:: cpp + + #include <ts/ts.h> + +.. function:: TSReturnCode TSHttpTxnVerifiedAddrSet(TSHttpTxn txnp, const struct sockaddr *addr) + +Description +=========== + +This function enables plugins to provide a reliable client IP address for |TS| and other plugins. +This is useful if there is a proxy in front of |TS| and it forwards client's IP address by HTTP header field, PROXY protocol, etc. +Plugins that call this function are expected to check the validity of the IP address. + +The provided address will be used for remap ACL if :ts:cv:`proxy.config.acl.subjects` is set to `PLUGIN`. +Plugins can get the provided address by calling the getter function bewlow if those need client's real IP address. Review Comment: `bewlow` ########## doc/developer-guide/api/functions/TSHttpTxnVerifiedAddrSet.en.rst: ########## @@ -0,0 +1,64 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed + with this work for additional information regarding copyright + ownership. The ASF licenses this file to you under the Apache + License, Version 2.0 (the "License"); you may not use this file + except in compliance with the License. You may obtain a copy of + the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing + permissions and limitations under the License. + +.. include:: ../../../common.defs + +.. default-domain:: cpp + +TSHttpTxnVerifiedAddrSet +************************ + +Sets a client IP address verified by a plugin. + +Synopsis +======== + +.. code-block:: cpp + + #include <ts/ts.h> + +.. function:: TSReturnCode TSHttpTxnVerifiedAddrSet(TSHttpTxn txnp, const struct sockaddr *addr) + +Description +=========== + +This function enables plugins to provide a reliable client IP address for |TS| and other plugins. +This is useful if there is a proxy in front of |TS| and it forwards client's IP address by HTTP header field, PROXY protocol, etc. +Plugins that call this function are expected to check the validity of the IP address. + +The provided address will be used for remap ACL if :ts:cv:`proxy.config.acl.subjects` is set to `PLUGIN`. +Plugins can get the provided address by calling the getter function bewlow if those need client's real IP address. + + +TSHttpTxnVerifiedAddrGet +************************ + +Gets the client IP address verified by a plugin. + +Synopsis +======== + +.. code-block:: cpp + + #include <ts/ts.h> + +.. function:: TSReturnCode TSHttpTxnVerifiedAddrGet(TSHttpTxn txnp, const struct sockaddr **addr) + +Description +=========== + +This is the getter version for the above setter. This returns 1 if a verified address is available. +Please note that a port number is not always available even if the function returns 1. Review Comment: It's probably good to explicitly say that the memory for the `addr` output parameter is managed by ATS core and should not be freed by the caller. ########## doc/admin-guide/plugins/realip.en.rst: ########## @@ -0,0 +1,86 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + + .. include:: ../../common.defs + +.. _admin-plugins-realip: + +Real IP Plugin +******************* + +Description +=========== +The `realip` plugin reads an IP address from a specified data source such as HTTP header field, and make it available for ATS and Review Comment: `make it` -> `makes it` ########## doc/developer-guide/api/functions/TSHttpTxnVerifiedAddrSet.en.rst: ########## @@ -0,0 +1,64 @@ +.. Licensed to the Apache Software Foundation (ASF) under one or more + contributor license agreements. See the NOTICE file distributed + with this work for additional information regarding copyright + ownership. The ASF licenses this file to you under the Apache + License, Version 2.0 (the "License"); you may not use this file + except in compliance with the License. You may obtain a copy of + the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied. See the License for the specific language governing + permissions and limitations under the License. + +.. include:: ../../../common.defs + +.. default-domain:: cpp + +TSHttpTxnVerifiedAddrSet +************************ + +Sets a client IP address verified by a plugin. + +Synopsis +======== + +.. code-block:: cpp + + #include <ts/ts.h> + +.. function:: TSReturnCode TSHttpTxnVerifiedAddrSet(TSHttpTxn txnp, const struct sockaddr *addr) + +Description +=========== + +This function enables plugins to provide a reliable client IP address for |TS| and other plugins. +This is useful if there is a proxy in front of |TS| and it forwards client's IP address by HTTP header field, PROXY protocol, etc. +Plugins that call this function are expected to check the validity of the IP address. + +The provided address will be used for remap ACL if :ts:cv:`proxy.config.acl.subjects` is set to `PLUGIN`. Review Comment: Probably good to explicitly say that ATS core makes and maintains its own copy of the memory from `addr`. ########## doc/admin-guide/plugins/realip.en.rst: ########## @@ -0,0 +1,86 @@ +.. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + + .. include:: ../../common.defs + +.. _admin-plugins-realip: + +Real IP Plugin +******************* + +Description +=========== +The `realip` plugin reads an IP address from a specified data source such as HTTP header field, and make it available for ATS and +its plugins as the verified client address. + +To use the verified client IP address for ACL, :ts:cv:`proxy.config.acl.subjects` needs to be set to `PLUGIN`. +Similary, if you want to use the IP address on header_rewrite plugin, its `INBOUND_IP_SOURCE` needs to be set to `PLUGIN`. + + +Configuration +============= + +To enable the `realip` plugin, insert the following line in :file:`plugin.config`: + + realip.so <config.yaml> + +The plugin supports 2 mode: + +simple +------ + +The plugin reads an IP address from a specified HTTP header field. These settings bewlow are available for this mode: Review Comment: `bewlow` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: github-unsubscr...@trafficserver.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org
