netadm 프로젝트에서의 개발. jeho-park, netadm@kernelproject.org v0.1, 15. feb 2006 GPL version 2. netadm 프로젝트에서의 개발. -------------------------------------------------------------------------------------- 목차 1. 서론. 2. 소스 디렉토리 설명. 3. 전체 구조. 4. 기능 추가 방법. 5. IPC 6. 코딩 스타일. 7. Library 추가. -------------------------------------------------------------------------------------- 1. 서론. 본 문서는 netadm 프로젝트에 개발자로 참여하고픈 분들에게 현재까지 netadm 프로젝트에서 개발된 개발 소스의 구조에서 부터 각각 구현된 모듈의 구조등을 설명하여 처음 참여하시는 분들의 빠른 적응을 하도록 돕기 위하여 만들어졌습니다. 더불어 새로 참여하신 개발자분들이 이미 netadm프로젝트에서 소기의 목적을 위해 만들어진 내부 라이브러리및 코딩 스타일을 설명하여 일관성있는 코드를 지속적으로 유지 및 발전시켜 궁극적으로 원활한 프로젝트 활동을 위해 만들어졌습니다. 2. 소스 디렉토리 설명. 현재 netadm프로젝트에서는 gwc프로그램을 개발 및 관리 중이며 gwc의 주요 기능은 모니터링, QoS 그리고 flow control입니다. 소스 구조는 간략히 아래와 같은 구조를 가진다. /gwc +------- /doc: 참조문서. | +------- /elib: gwc에서 사용하는 외부의 라이브러리이며, 미리 | 컴파일된 archive형태로 관리되고 있다. | +------- /gwcadmd: wireless관련한 기능을 제공하기 위해 구현된 | 데몬이며, gwc 초기 설치 시 wireless 내용을 | 설정하지 않으면 아무 동작도 하지 않으며 무한 | 루프를 돈다. | 만약, wireless 설정을 초기 설치 시 했을때는 | 무선랜 802.11a/b/g 를 구분하여 지속적으로 | 관련 정보를 업데이트를 하기도 하며 | wireless signal power modules을 제어하는 기능을 | 사용 할 수 있다. | +------- /gwccli: cli command | +------- /gwcguid: GUI 데몬, 세부 내용은 아래 내용 참조. | +------- /gwclib: 내부 라이브러리, 세부 내용은 아래 내용 참조. | +------- /include: gwclib의 소스와 1:1대응되는 헤더화일 포함. | 세부 내용은 아래 내용 참조. | +------- /pf: 패킷 필터링과 관련하여 nfhook 핸들러등을 정의한 커널 모듈. | +------- /scripts: 설치 스크립(install.sh), 운영스크립(gwc), 디폴트로 설치 시 시스템에 복사될 syslog설정화일, 마지막으로 설치 시 시스템에 설치 될 SNMP 설정 및 MIB화일을 압축한 gz화일이 있다. gwc의 경우 아래의 내용별로 헤더와 소스 화일이 분류되어 있습니다. [헤더 화일] h1. 내부 자료구조를 정의한 헤더. h2. 전역적인 configuration 및 경로를 정의한 헤더. h3. string형태의 메세지를 정의한 헤더. h4. 프로그램 특성과 무관하지만 자주 사용될 라이브러리 함수를 익스포트한 헤더. h5. 프로그램의 주요 기능을 처리할 프로시저 선언 및 익스포트한 헤더. h6. 데몬에서 독립적으로 사용할 자료구조 및 매크로등을 정의한 헤더. [소스 화일] c4. h4관련한 라이브러리 함수 정의 소스. c5. h5관련한 프로그램의 주요 기능과 관련한 프로시저를 정의한 소스. d1. 데몬의 메인 루틴과 관련해 정의한 소스. 아래의 내용은 위의 내용을 기준으로 현재 gwc 소스 구성을 보입니다. [헤더화일] h1. 내부 자료구조를 정의한 헤더. 경로: include 화일: sysdef.h, sysshm.h 세부설명: sysdef.h: 객체 정의 sysshm.h: sysdef.h에서 정의한 객체를 하나의 자료구조로 구성하며, shared memory를 통해 시스템 전역적으로 접근 가능하도록 함. h2. 전역적인 configuration 및 경로를 정의한 헤더. 경로: include 화일: global.h 세부설명: global.h: 컴파일 시점에 결정될 수 있는 여러 매크로 변수등을 정의하였으며, 여기서 정의된 변수는 시스템 전역적으로 약속된 설정등과 연관됩니다. 가령, 시스템 시작, 종료를 수행하는 스크립트의 경로, 내부 프로그램에서 참조하는 외부 경로, 패키지 버전 정보, IPC용도의 임시화일 경로 h3. string형태의 메세지를 정의한 헤더. 경로: include 화일: message.h 세부 설명: message.h: 프로그램 내부적으로 사용할 스트링을 정의한 헤더로서, 가령 cli command 의 help메세지, 내부 처리 에러와 관련된 메세지등입니다. h4. 프로그램 특성과 무관하지만 자주 사용될 라이브러리 함수를 익스포트한 헤더. 경로: include 화일: confio.h, confutil.h, slog.h, sysioctl.h, sysipc.h, sysnio.h, syssnmp.h, systime.h, sysutil.h 세부 설명: confio.h: configuration화일에 대한 save, load 기능함수 선언. confutil.h: IPC등과 관련되어 사용될 유틸함수 선언. slog.h: 개발시 편의를 위한 syslog sysioctl.h: pf와 관련하여 io interface를 위한 헤더. sysnio.h: 개발시 편의를 위한 bsd socket관련 라이브러리 헤더. syssnmp.h: snmp 라이브러리. systime.h: timiing 및 timer를 위한 라이브러리. sysutil.h: 위의 내용에 해당되지 않지만 시스템 전역적으로 사용될 라이브러리. h5. 프로그램의 주요 기능을 처리할 프로시저 선언 및 익스포트한 헤더. 경로: include 화일: confproc.h 세부 설명: confproc.h: IPC를 통해 cli command나 gui로 부터 요청 시 실질적인 내부 요청처리를 하는 루틴의 헤더. 세부 설명: h6. 데몬에서 독립적으로 사용할 자료구조 및 매크로등을 정의한 헤더. 경로: gwcguid 화일: apc.h, callback.h, dump.h, fwc.h, interface.h, qos.h, support.h 세부 설명: apc.h: GUI 데몬에서 모니터링 UI 관련한 루틴 및 자료구조 포함. callback.h: GUI데몬에서 callback함수 관련 헤더. dump.h: 현재 사용 않함. fwc.h: GUI 데몬에서 flow control UI 관련한 루틴 및 자료구조 포함. interface.h: GUI의 주요 루틴과 관련한 헤더. qos.h: GUI 데몬에서 QoS UI 관련한 루틴 및 자료구조 포함. support.h: glade 툴로 만들어진 화일로서 내부 callback등 처리 시 사용되는 내부 루틴관련 헤더. [소스 화일] c4. h4관련한 라이브러리 함수 정의 소스. 경로: gwclib 화일: confio.c confutil.c slog.c sysipc.c sysnio.c syssnmp.c systime.c sysutil.c 세부 설명: confio.c: configuration화일에 대한 save, load 기능함수 정의. confutil.c: IPC 유틸함수 정의. slog.c: syslog 래퍼 함수 정의. sysnio.c: 소켓 함수를 내용별로 요약한 라이브러리 함수 정의. syssnmp.c: snmp 라이브러리 함수 정의. systime.c: timiing 및 timer를 위한 라이브러리 정의. sysutil.c: 위의 내용에 해당되지 않지만 시스템 전역적으로 사용될 라이브러리 정의. c5. h5관련한 프로그램의 주요 기능과 관련한 프로시저를 정의한 소스. 경로: gwclib 화일: confproc.c 세부 설명: confproc.c: syscmd, sysclist의 두 ipc용도의 함수를 통해 궁극적으로 호출되는 각각의 명령에 대한 처리 함수를 포함한다. 그래서 cli command에서 실행가능한 명령들은 confproc.c의 각 함수들과 1:1대응된다. 3. 전체 구조. 현재 gwc는 cli command와 GUI 인터페이스를 통해 각각의 기능들을 사용자에게 제공합니다. 내부적인 전체 구조는 아래와 같습니다. (시스템 설정) +--> shared memory | +----> cli command <----> ipc_msg() <--> procedures<-+ | ( gwccli ) /|\ | | | +--> 시스템콜 사용자 <--+ | | | | | | \|/ +----> GUI <-> handler <-> syscmd(), sysclist() ( gwcguid ) [gwc 전체 구조] 위의 그림에서와 같이 gwc는 cli command 또는 GUI interface를 통해 사용자의 요청을 입력 받아 해당 요청을 처리합니다. cli command의 사용자 요청 처리는 아래와 같은 일련의 과정을 거칩니다. a. main() b. gwc에서 초기화한 shared memory에 attach. c. 사용자 요청 스트링 입력 받음. d. ipc_msg() 호출 d-1. ipc_msg()내부적으로 해당 procedure호출. d-2. 해당 procedure는 고유 기능을 사용자 요청대로 처리하기 위해 shared memory와 시스템 콜을 사용. e. ipc_msg()의 결과를 standard out으로 출력. GUI 데몬은 사용자의 요청 처리를 하기 위해 cli command와 유사한 기능 수행을 유사하지만 GUI 처리를 위해 추가의 내용이 삽입됩니다. a. main b. GUI 화면 초기화 및 버튼등의 callback등록. c. show window d. gtk_main (), 이벤트 대기 모드. e. 사용자 요청 이벤트 발생. f. case1. 사용자의 요청이 단순한 출력(list) 요청 시 sysclist()호출. case2. 사용자의 요청이 특정 데이터를 설정에 넣거나 apply등의 형태면 syscmd()를 호출. g. sysclist, syscmd함수는 내부적으로 cli command와 통일하게 ipc_msg()호출. g-1. ipc_msg()내부적으로 해당 procedure호출. g-2. 해당 procedure는 고유 기능을 사용자 요청대로 처리하기 위해 shared h. sysclist()를 호출한 경우 해당 string list를 GUI에 출력. syscmd()를 호출한 경우 단순히 성공 실패 여부만 GUI의 statusbar나 에러 윈도우로 출력. 4. 기능 추가 방법. 아래의 내용은 위의 gwc전체 구조를 감안하여 실제 하나의 기능을 추가할 시에 수행되는 일련의 과정을 보여줍니다. 4.1. cli command로 기능 추가 단계. a. 기능 설계 -> b. cli 인터페이스 작성 -> c. 자료구조 추가 -> d. 핸들러 구현. 위의 단계만으로도 cli command를 통한 해당 기능이 추가됩니다. 4.2. GUI 에서 기능 개발 단계. GUI 개발은 위에서 해당 기능을 cli command구현이 완료된 후, 시작이 되며 아래와 같은 개발 단계를 거칩니다. e. 기본 UI 및 기능에 따른 이벤트 (추가/삭제/적용)에 따른 기본 함수 프로토타입 개발 -> f. syscmd, sysclist란 IPC함수를 통해 핸들러 호출. 위의 f. 과정까지 작업하면 개략적인 기능의 전체 구현이 완료됩니다. 4.3. 실제 작업 시 세부 내용. 아래의 내용은 앞의 4.1, 4.2에서 보인 a 부터 f 단계에 대해 작업 시 관련되어 있는 소스들과 간략히 대응되는 작업을 보다 세부적으로 설명합니다. a. 기능 설계. b. cli 인터페이스 작성. b-1. include/sysipc.h의 sys_cmd_e 에 핸들러의 index를 정의. b-2. include/confproc.h에 핸들러의 함수 원형 선언. b-3. gwclib/conftab.c 안의 "cmdtab" table map에 b-1.의 index와 b-2.의 함수 포인터 그리고 cli command의 help메세지 인덱스를 매핑. b-4. include/message.h에 b-3.에서 선언한 help메세지를 정의. b-5. gwclib/confproc.c에 b-2.에서 선언한 함수 원형 정도의 함수 skeleton만 정의. b-5.의 과정까지 작업이 완료되면 gwc의 컴파일이 원활이 되야 하며 cli command실행이 가능합니다. 단, 실제 b-5에서 내부 루틴을 구현하지 않았으니 해당 cli command를 실행해도 아무 동작은 않합니다. c. 자료구조 추가. 이제 실제 기능을 구현 및 gwc의 공유메모리에 저장될 자료구조를 정의하는 단계입니다. sysdef.h 에는 필요로 하는 object를 정의하며 sysshm.h에는 sysdef.h에 정의한 object를 포함하는 공유메모리(sm_t 구조체) 에 적절히 포함시킴니다. d. 핸들러 추가. b-5.에서 구현한 skeleton함수에 대한 실제 구현을 합니다. 설정을 출력하는 기능인 경우 csm포인터를 통해 c.의 과정에서 추가한 자료구조에 접근하며, 사용자 입력 저장 시에는 saveconf 라이브러리 함수를 통해 설정화일에 저장을 합니다. 그 외에 필요 시 시스템 콜을 호출하여 사용자 요청을 적절히 처리합니다. 위의 d의 과정까지 완료되면 cli command를 통해 실제 기능 수행이 가능해집니다. e. 기본 UI 및 기능에 따른 이벤트 (추가/삭제/적용)에 따른 기본 함수 프로토타입 개발 e-1. 기능에 따른 GUI 디자인을 한 후 glade와 같은 개발툴을 사용하여 gtk코드를 만듭니다. e-2. e-1. 에서 추출한 gtk코드를 현재 gwcguid내의 interface.c에 추가합니다. 단 callback함수는 callback.c에 추가. f. syscmd, sysclist란 IPC함수를 통해 핸들러 호출. e-2에서 구현된 callback함수 안에 실제 처리 (ipc_msg를 통해 d.의 과정에서 완료한 핸들러를 궁극적으로 호출하기 위해)위해 syscmd, sysclist를 사용하여 GUI 구현을 완료합니다. 참고로 아래는 GUI 데몬에서 syscmd, sysclist를 사용 하는 구체적인 설명을 합니다. 4.4. gwcguid 데몬에서 sysclist, syscmd 를 통한 IPC. 4.4.1. syscmd함수. 설정 내용을 출력하는 내용 외에 모든 동작은 syscmd()를 호출하여 IPC합니다. 가령 설정의 추가 또는 설정 적용이 그 예입니다. void *syscmd(sys_cmd_e cmd, ...); - sys_cmd_e : sysipc.h 에 정의 - ... : command에 따라 가변적인 입력이므로 conftab.c 에 CMD_XXX에 매핑된 실제 처리 함수의 입력 처리를 참조한다. 사용예) "class name", "class type"을 사용자로 부터 전달받아 class 추가하는 루틴. char *error = NULL; char name [OL] char type[10]; strcpy(name, 입력받은값); /* class name */ strcpy(type, 입력받은값); /* class type */ error = syscmd ( CMD_ADD_TC_CLASS, name, type, EOA); if ( !error ) { /* 성공 */ /* 성공 시의 window 루틴 코드 */ } else { /* 실패 */ /* 실패한 경우이므로 해당 이유를 표시하는 윈도우를 생성한다. */ /* 단, 실패원인은 error[0] 스트링에 있으므로 이를 출력한다. */ call error_window ("%s", error); } /* 실패한 경우 syscmdfree()는 반드시 호출되야함, 성공한 경우는 error이 NULL이지만 * 호출하면 그냥 리턴하므로 실패/성공과 무관하게 호출하도록 하는게바람짐.*/ syscmdfree (error); return; 4.4.2. sysclist 함수. 설정등의 정보를 출력하는 형태의 동작은 gwcguid데몬에서 sysclist를 통해 공유메모리에 접근합니다. char ** sysclist(sys_cmd_e cmd, char *what, int *col, int *row) - sys_cmd_e : sysipc.h에 미리 정의된command 의 인덱스(CMD_XXX..) - what : NULL - col : 얻어온 list(리턴 값의)의 열의 개수 - row : 얻어온 list의 행의 개수 리턴 값 char** 인 이중배열 예제) radiusd데몬의 pid를 얻어와서 출력하는 예제. char **list; int cols; int rows; list = sysclist(CMD_GET_RADIUSD_PID, NULL, &cols, &rows); if ( rows == -1 ){ /* 실패 */ /* 실패 이유 : list[0] */ /* In this case list, list must not free, because this list is not allot by malloc it just a arry in internally list[0] = &buf , whenever error occur in internally, free first called in internally so we will not need to free again */ error window ("%s", list[0]) return; } else { /* 성공 */ } sysclistfree (list); /* must be called whever success */ return; 4.4.3. syscmdfree/sysclist 유의 사항. 위의 2에서 보인 사용 에를 따르지 않을 경우 memory leak가 생기므로 주의한다! 4.4.4. sysclist의 리턴값인 list list는 2차 배열의 시작 주소를 가지고 있다. 예를 들어 pcols =2, prows =3 인 경우, 아래의 형태로 list가 넘어온다 +------------------------------------------------------------ | 0 | 1 | 2 | 3 | 4 | 5 | +------------------------------------------------------------ /| row(1) row(2) row(3) | list 5. IPC. gwc에서는 2가지의 IPC를 사용하고 있습니다. - shared memory. - unix domain socket. 5.1. shared memory. 위에서의 shared memory는 현재 gwc의 config의 정보를 다른 프로세스와 공유하기 위해 사용되면 궁극적인 interface 는 위에서 언급된 ipc_msg, syscmd, sysclist입니다. 위의 3가지 interface를 사용하기 위해 cli command와 GUI데몬은 각각 gwcadmd가 초기화한 공유메모리에 attach, detach하는 절차를 가지며 아래는 그와 관련된 라이브러리 함수 사용을 보여줍니다. 5.1.1. attach, detach. [ attach 예제 ] #include "sysshm.h" extern sm_t *csm; if (cshmattach(&csm) < 0) { printf("Cannot attach SHM '%s'\n", strerror(errno)); ... } [ detach 예제 ] if (cshmdetach(csm) < 0) { printf("Cannot detach SHM '%s'\n", strerror(errno)); ... } 5.1.2. 공유 메모리 접근 및 동기화. 위의 attach과정이 성공하면 csm포인터를 통해 sm_t에 정의된 shared memory에 접근가능하게 됩니다. 하지만, 가급적 전체 시스템의 동기화등을 감안하여 프로세스에서 csm포인터를 통해 개별적인 read/write는 피하는 것이 좋습니다. 동기화 문제 발생 시, "memory segment fault" 또는 pf와 연관된 경우 kernel panic이 발생될 수 있습니다. shared memory에 대한 동기화의 해결책은 여러가지가 있을 수 있지만, 현재는 gwcadmd데몬에서 아래와 같은 방법으로 동기화 문제를 처리하고 있습니다. while (csm->shared_mutex == MUTEX_LOCK); /* UNLOCK 상태가 될때까지 blocking됨. */ csm->shared_mutex = MUTEX_LOCK; 처리할 코드 삽입.... csm->shared_mutex = MUTEX_UNLOCK; 5.2. unix domain socket. 현재 gwc는 unix domain socket을 좀더 편하게 사용하기 위해 아래와 같은 3개의 함수를 래퍼형태로 제공합니다. int sys_ipclisten(void); int sys_ipcconn(void); int sys_ipcclean(void); 현재는 gwccli 에서 사용자 요청을 받아 procedure에서 gwcadmd데몬과 통신을 위해 사용하고 있습니다. grep로 해당 부분을 찾아보시면 참조가 사용 시 유용할 수 있음을 아실겁니다. 6. 코딩 스타일. gnu style로 통일되기를 원합니다. 현재 gwc-v0.1-pre2까지는 gnu style이 잘 지켜지지 않았지만 추후 작업 시에는 indent의 gnu 옵션을 통해 gnu style로 통일 되었으면 합니다. 예) 구현된 소스화일 내용 모두를 gnu style로 바꾸는 예. $indent -gnu test.c 7. Library 추가. 종종 사용될 것으로 예상되는 루틴은 2장 "소스 디렉토리 설명" 중반부터 설명된 [헤더화일] [소스]의 분류를 참조하여 해당 소스에 추가하기를 추천합니다. Contact to: linuxpark.netadm@gmail.com, 2006. 02. 19. (sun) 22:24:08 KST